inc/FUiCtrlHeader.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FUiCtrlHeader.h
  20  * @brief       This is the header file for the %Header class.
  21  *
  22  * This header file contains the declarations of the %Header class.
  23  */
  24 #ifndef _FUI_CTRL_HEADER_H_
  25 #define _FUI_CTRL_HEADER_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseTypes.h>
  29 #include <FBaseString.h>
  30 #include <FGrpBitmap.h>
  31 #include <FGrpColor.h>
  32 #include <FGrpRectangle.h>
  33 #include <FUiControl.h>
  34 #include <FUiIActionEventListener.h>
  35 #include <FUiCtrlAnimation.h>
  36 #include <FUiCtrlButtonItem.h>
  37 #include <FUiCtrlHeaderItem.h>
  38 #include <FUiCtrlForm.h>
  39
  40 namespace Tizen { namespace Ui { namespace Controls
  41 {
  42 class _HeaderImpl;
  43
  44 /**
  45  * @enum        HeaderStyle
  46  *
  47  * Defines the possible styles of a %Header control.
  48  *
  49  * @since       2.0
  50  */
  51 enum HeaderStyle
  52 {
  53         HEADER_STYLE_TITLE,                             /**< The title style */
  54         HEADER_STYLE_TITLE_BUTTON,              /**< The title button style */
  55         HEADER_STYLE_SEGMENTED,                 /**< The segmented style */
  56         HEADER_STYLE_SEGMENTED_WITH_TITLE,  /**< The segmented style with title */
  57         HEADER_STYLE_TAB,                                       /**< The tab style */
  58         HEADER_STYLE_TAB_WITH_TITLE,            /**< The tab with title style */
  59         HEADER_STYLE_BUTTON,                            /**< The button style */
  60         HEADER_STYLE_TAB_LARGE                  /**< The large tab style @b Since: @b 2.2 */
  61 };
  62
  63 /**
  64  * @enum        HeaderAnimationPosition
  65  *
  66  * Defines the possible positions of the waiting animation of a header.
  67  *
  68  * @since   2.0
  69  */
  70 enum HeaderAnimationPosition
  71 {
  72         HEADER_ANIMATION_POSITION_TITLE,        /**< The title animation */
  73         HEADER_ANIMATION_POSITION_BUTTON_LEFT,  /**< The left button animation */
  74         HEADER_ANIMATION_POSITION_BUTTON_RIGHT  /**< The right button animation */
  75 };
  76
  77 /**
  78  * @class       Header
  79  * @brief       This class is an implementation of a %Header control.
  80  *
  81  * @since       2.0
  82  *
  83  * The %Header class displays a multi-purpose area at the top of the screen that usually acts as a placeholder for descriptive
  84  * contents, such as a title of the current screen. It can also contain buttons for performing various user-defined tasks.
  85  *
  86  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_header.htm">Header</a>.
  87  *
  88  * The following examples demonstrate how to use the %Header class.
  89  *
  90  * - Constructing a header: @n
  91  * When creating a Form, specify the FORM_STYLE_HEADER parameter in the Form::Construct() method.
  92  *
  93  * @code
  94  * // Initializes
  95  * bool
  96  * TestForm::Initialize(void)
  97  * {
  98  *      Construct(FORM_STYLE_NORMAL | FORM_STYLE_PORTRAIT_INDICATOR | FORM_STYLE_HEADER );
  99  * }
 100  * @endcode
 101  *
 102  * - Using the header: @n
 103  * Gets the header with the GetHeader() method, and sets the header style.
 104  *
 105  * @code
 106  * bool
 107  * TestForm::Initialize(void)
 108  * {
 109  *      Header* pHeader = GetHeader();
 110  *      pHeader->SetStyle(HEADER_STYLE_SEGMENTED);
 111  * }
 112  * @endcode
 113  *
 114  * - Adding items to the header: @n
 115  * Adds HeaderItems or ButtonItems according to the header style. The action ID registered in the Construct() method is notified
 116  * when items are touched.
 117  *
 118  * @code
 119  * bool
 120  * TestForm::Initialize(void)
 121  * {
 122  *      HeaderItem headerItem;
 123  *      headerItem.Construct(ID_HEADER_ITEM);
 124  *      headerItem.SetText("HeaderItem");
 125  *
 126  *      pHeader->AddItem(headerItem);
 127  *
 128  *      ButtonItem buttonItem;
 129  *              buttonItem.Construct(BUTTON_ITEM_STYLE_ICON, ID_HEADER_BUTTON);
 130  *      buttonItem.SetIcon(BUTTON_ITEM_STATUS_NORMAL, __pBitmap);
 131  *
 132  *      pHeader->SetButton(BUTTON_POSITION_LEFT, buttonItem);
 133  *
 134  * }
 135  * @endcode
 136  *
 137  * - Setting the header title and description:
 138  *
 139  * @code
 140  * bool
 141  * TestForm::Initialize(void)
 142  * {
 143  *      pHeader->SetTitleText(L"Header Title");
 144  *      pHeader->SetDescriptionText(L"Description Text");
 145  * }
 146  * @endcode
 147  */
 148 class _OSP_EXPORT_ Header
 149         : public Tizen::Ui::Control
 150 {
 151
 152 public:
 153         /**
 154          * Adds the specified header item.
 155          *
 156          * @since               2.0
 157          *
 158          * @return      An error code
 159          * @param[in]   item                The HeaderItem object to add
 160          * @exception   E_SUCCESS           The method is successful.
 161          * @exception   E_MAX_EXCEEDED      The number of items has exceeded the maximum limit.
 162          * @exception   E_INVALID_ARG       A specified input parameter is invalid. @n
 163          *                                                                      The specified item is not constructed.
 164          * @exception   E_SYSTEM            A system error has occurred.
 165          * @remarks     The %Header control does not throw any exception even though the same action ID is assigned to multiple items. @n
 166          *              However, the content of the specified item is copied to the %Header control.
 167          */
 168         result AddItem(const HeaderItem& item);
 169
 170
 171         /**
 172          * Inserts the header item at the specified index.
 173          *
 174          * @since               2.0
 175          *
 176          * @return      An error code
 177          * @param[in]   itemIndex           The index where the item should be inserted
 178          * @param[in]   item                The HeaderItem object to insert
 179          * @exception   E_SUCCESS           The method is successful.
 180          * @exception   E_MAX_EXCEEDED      The number of items has exceeded the maximum limit.
 181          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the data structure, or the index is greater than or equal to
 182          *                                                              the number of elements or less than @c 0.
 183          * @exception   E_INVALID_ARG       A specified input parameter is invalid. @n
 184          *                                                                      The specified @c item is not constructed.
 185          * @exception   E_SYSTEM            A system error has occurred.
 186          * @remarks     The %Header control does not throw any exception even though the same action ID is assigned to multiple items. @n
 187          *              However, the content of the specified item is copied to the %Header control.
 188          */
 189         result InsertItemAt(int itemIndex, const HeaderItem& item);
 190
 191
 192         /**
 193          * Checks whether a button item is set at the specified position.
 194          *
 195          * @since               2.0
 196          *
 197          * @return              @c true if the button item is set at the specified position, @n
 198          *                              else @c false
 199          * @param[in]   position                        The position of the button item
 200          * @exception   E_SUCCESS                       The method is successful.
 201          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 202          */
 203         bool IsButtonSet(ButtonPosition position) const;
 204
 205
 206         /**
 207          * Gets the state of the specified button item.
 208          *
 209          * @since               2.0
 210          *
 211          * @return      The state of the button item at the specified position, @n
 212          *                              else @c BUTTON_ITEM_STATUS_NORMAL if an error occurs
 213          * @param[in]   position                        The position of the button item
 214          * @exception   E_SUCCESS                       The method is successful.
 215          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 216          *                                                                      There is no button set at the specified position.
 217          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 218          */
 219         ButtonItemStatus GetButtonStatus(ButtonPosition position) const;
 220
 221
 222         /**
 223          * Gets the color of the button item for the specified state.
 224          *
 225          * @since               2.0
 226          *
 227          * @return              The color of the button item, @n
 228          *                              else RGBA (0,0,0,0) if an error occurs
 229          * @param[in]   status                          The status of the button item
 230          * @exception   E_SUCCESS                       The method is successful.
 231          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 232          * @see         SetButtonColor()
 233          */
 234         Tizen::Graphics::Color GetButtonColor(ButtonItemStatus status) const;
 235
 236
 237         /**
 238          * Gets the text color of the button item for the specified state.
 239          *
 240          * @since               2.0
 241          *
 242          * @return      The text color of the button item, @n
 243          *                              else RGBA (0,0,0,0) if an error occurs
 244          * @param[in]   status                          The status of the button item
 245          * @exception   E_SUCCESS                       The method is successful.
 246          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 247          */
 248         Tizen::Graphics::Color GetButtonTextColor(ButtonItemStatus status) const;
 249
 250
 251         /**
 252          * Gets the description text of the %Header control that has the title style.
 253          *
 254          * @since               2.0
 255          *
 256          * @return              The description text, @n
 257          *                              else an empty string if an error occurs
 258          * @exception   E_SUCCESS                       The method is successful.
 259          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 260          */
 261         Tizen::Base::String GetDescriptionText(void) const;
 262
 263
 264         /**
 265          * Gets the description text color of the %Header control that has the title style.
 266          *
 267          * @since               2.0
 268          *
 269          * @return              The description text color, @n
 270          *                              else RGBA (0,0,0,0) if an error occurs
 271          * @exception   E_SUCCESS                       The method is successful.
 272          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 273          */
 274         Tizen::Graphics::Color GetDescriptionTextColor(void) const;
 275
 276
 277         /**
 278          * Gets the color of the header item for the specified item state.
 279          *
 280          * @since               2.0
 281          *
 282          * @return              The color of the item, @n
 283          *                              else RGBA (0,0,0,0) if an error occurs
 284          * @param[in]   status                          The item status
 285          * @exception   E_SUCCESS                       The method is successful.
 286          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 287          * @see                 SetItemColor()
 288          */
 289         Tizen::Graphics::Color GetItemColor(HeaderItemStatus status) const;
 290
 291
 292         /**
 293          * Gets the total number of header items.
 294          *
 295          * @since               2.0
 296          *
 297          * @return              The total number of header items, @n
 298          *                              else @c -1 if an error occurs
 299          * @exception   E_SUCCESS                       The method is successful.
 300          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 301          */
 302         int GetItemCount(void) const;
 303
 304
 305         /**
 306          * Gets the state of the specified header item.
 307          *
 308          * @since               2.0
 309          *
 310          * @return              The item status
 311          * @param[in]   itemIndex                       The index of the item
 312          * @param[out]  status                          The item status
 313          * @exception   E_SUCCESS                       The method is successful.
 314          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure. @n
 315          *                                                                      The index is greater than or equal to the number of elements or less than @c 0.
 316          */
 317         result GetItemStatus(int itemIndex, HeaderItemStatus& status) const;
 318
 319
 320         /**
 321          * Gets the text color of the header item for the specified item state.
 322          *
 323          * @since               2.0
 324          *
 325          * @return              The item's text color, @n
 326          *                              else RGBA (0,0,0,0) if an error occurs
 327          * @param[in]   status                          The item status
 328          * @exception   E_SUCCESS                       The method is successful.
 329          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 330          */
 331         Tizen::Graphics::Color GetItemTextColor(HeaderItemStatus status) const;
 332
 333
 334         /**
 335          * Gets the style of the %Header control.
 336          *
 337          * @since               2.0
 338          *
 339          * @return              The %Header control style, @n
 340          *                              else @c HEADER_STYLE_TITLE if an error occurs
 341          * @exception   E_SUCCESS                       The method is successful.
 342          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 343          */
 344         HeaderStyle GetStyle(void) const;
 345
 346
 347         /**
 348          * Gets the index of the currently selected item.
 349          *
 350          * @since               2.0
 351          *
 352          * @return              The selected item index, @n
 353          *                              else @c -1 if an error occurs
 354          * @exception   E_SUCCESS                                       The method is successful.
 355          * @exception   E_UNSUPPORTED_OPERATION         This operation is supported when the style of the %Header control is ::HEADER_STYLE_SEGMENTED, @n
 356          *                                                                                              ::HEADER_STYLE_SEGMENTED_WITH_TITLE, ::HEADER_STYLE_TAB, ::HEADER_STYLE_TAB_WITH_TITLE or ::HEADER_STYLE_TAB_LARGE.
 357          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 358          */
 359         int GetSelectedItemIndex(void) const;
 360
 361
 362         /**
 363          * Gets the title text of the %Header control that has the title style.
 364          *
 365          * @since               2.0
 366          *
 367          * @return              The title text, @n
 368          *                              else an empty string if an error occurs
 369          * @exception   E_SUCCESS                       The method is successful.
 370          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 371          */
 372         Tizen::Base::String GetTitleText(void) const;
 373
 374
 375         /**
 376          * Gets the title text color of the %Header control that has the title style.
 377          *
 378          * @since               2.0
 379          *
 380          * @return              The title text color, @n
 381          *                              else RGBA (0,0,0,0) if an error occurs
 382          * @exception   E_SUCCESS                       The method is successful.
 383          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 384          */
 385         Tizen::Graphics::Color GetTitleTextColor(void) const;
 386
 387
 388         /**
 389          * Gets the color of the %Header control.
 390          *
 391          * @since               2.0
 392          *
 393          * @return              The header color, @n
 394          *                              else RGBA (0,0,0,0) if an error occurs
 395          * @exception   E_SUCCESS                       The method is successful.
 396          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 397          */
 398         Tizen::Graphics::Color GetColor(void) const;
 399
 400
 401         /**
 402          * Gets the status of the waiting animation at the specified position.
 403          *
 404          * @since               2.0
 405          *
 406          * @return              The animation status
 407          * @param[in]   animationPos            The waiting animation position
 408          * @exception   E_SUCCESS                       The method is successful.
 409          * @remarks             The specific error code can be accessed using the GetLastResult() method. @n
 410          *              This method returns @c ANIMATION_STOPPED, if no animation is in progress at the specified position.
 411          * @see                 PauseWaitingAnimation()
 412          * @see                 PlayWaitingAnimation()
 413          * @see                 StopWaitingAnimation()
 414          */
 415         AnimationStatus GetWaitingAnimationStatus(HeaderAnimationPosition animationPos) const;
 416
 417
 418         /**
 419          * Pauses the waiting animation at the specified position.
 420          *
 421          * @since               2.0
 422          *
 423          * @return              An error code
 424          * @param[in]   animationPos                    The waiting animation position
 425          * @exception   E_SUCCESS                               The method is successful.
 426          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
 427          *                                                                              No waiting animation is in progress at the specified position.
 428          * @exception   E_SYSTEM                                A system error has occurred.
 429          * @see                 PlayWaitingAnimation()
 430          * @see                 StopWaitingAnimation()
 431          */
 432         result PauseWaitingAnimation(HeaderAnimationPosition animationPos);
 433
 434
 435         /**
 436          * Starts the waiting animation at the specified position.
 437          *
 438          * @since               2.0
 439          *
 440          * @return              An error code
 441          * @param[in]   animationPos                    The waiting animation position
 442          * @exception   E_SUCCESS                               The method is successful.
 443          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
 444          *                                                                              There is no button set at the specified position (except for @c HEADER_ANIMATION_POSITION_TITLE).
 445          * @exception   E_SYSTEM                                A system error has occurred.
 446          * @see                 SetButton()
 447          * @see                 IsButtonSet()
 448          * @see                 GetWaitingAnimationStatus()
 449          * @see                 PauseWaitingAnimation()
 450          * @see                 StopWaitingAnimation()
 451          */
 452         result PlayWaitingAnimation(HeaderAnimationPosition animationPos);
 453
 454
 455         /**
 456          * Removes all the button items.
 457          *
 458          * @since               2.0
 459          *
 460          * @return      An error code
 461          * @exception   E_SUCCESS       The method is successful.
 462          * @exception   E_SYSTEM        A system error has occurred.
 463          */
 464         result RemoveAllButtons(void);
 465
 466
 467         /**
 468          * Removes all the %Header control items.
 469          *
 470          * @since               2.0
 471          *
 472          * @return              An error code
 473          * @exception   E_SUCCESS                       The method is successful.
 474          * @exception   E_SYSTEM                        A system error has occurred.
 475          * @remarks             The left button, right button, and back button items are not removed.
 476          */
 477         result RemoveAllItems(void);
 478
 479
 480         /**
 481          * Removes the item at the specified index.
 482          *
 483          * @since               2.0
 484          *
 485          * @return              An error code
 486          * @param[in]   itemIndex                       The index of the item to remove
 487          * @exception   E_SUCCESS                       The method is successful.
 488          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure. @n
 489          *                                                                      The index is greater than or equal to the number of elements or less than @c 0.
 490          * @exception   E_SYSTEM            A system error has occurred.
 491          */
 492         result RemoveItemAt(int itemIndex);
 493
 494
 495         /**
 496          * Removes the button item at the specified position.
 497          *
 498          * @since               2.0
 499          *
 500          * @return      An error code
 501          * @param[in]   position        The position of the button item to remove
 502          * @exception   E_SUCCESS       The method is successful.
 503          * @exception   E_SYSTEM        A system error has occurred.
 504          * @remarks     If no button item is set at the specified position, the method returns @c E_SUCCESS.
 505          */
 506         result RemoveButtonAt(ButtonPosition position);
 507
 508
 509         /**
 510          * Sets the background bitmap image.
 511          *
 512          * @since               2.0
 513          *
 514          * @return      An error code
 515          * @param[in]   pBitmap                         The background image
 516          * @exception   E_SUCCESS                       The method is successful.
 517          * @exception   E_SYSTEM                        A system error has occurred.
 518          */
 519         result SetBackgroundBitmap(const Tizen::Graphics::Bitmap* pBitmap);
 520
 521
 522         /**
 523          * Sets the button item at the specified position.
 524          *
 525          * @since               2.0
 526          *
 527          * @return      An error code
 528          * @param[in]   position                        The position at which to set the specified button item
 529          * @param[in]   button                          The button item to set
 530          * @exception   E_SUCCESS                       The method is successful.
 531          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 532          *                                                                      The specified item is not constructed.
 533          * @exception   E_SYSTEM                        A system error has occurred.
 534          * @remarks     If there is an existing button item at the specified position, it is replaced with a new item. @n
 535          *              The contents of the specified item are copied.
 536          */
 537         result SetButton(ButtonPosition position, const ButtonItem& button);
 538
 539
 540         /**
 541          * Sets the button item color for the specified state.
 542          *
 543          * @since               2.0
 544          *
 545          * @return              An error code
 546          * @param[in]   status          The status of the button item
 547          * @param[in]   color           The button item color to set
 548          * @exception   E_SUCCESS       The method is successful.
 549          * @exception   E_SYSTEM            A system error has occurred.
 550          * @see         GetButtonColor()
 551          */
 552         result SetButtonColor(ButtonItemStatus status, const Tizen::Graphics::Color& color);
 553
 554
 555         /**
 556          * Enables or disables the button item at the specified position.
 557          *
 558          * @since       2.0
 559          *
 560          * @return      An error code
 561          * @param[in]   position                        The button item position
 562          * @param[in]   enable                          Set to @c true to enable the specified button item, @n
 563          *                                                                      else @c false to disable
 564          * @exception   E_SUCCESS                       The method is successful.
 565          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 566          *                                                                      There is no button set at the specified position.
 567          * @exception   E_SYSTEM            A system error has occurred.
 568          */
 569         result SetButtonEnabled(ButtonPosition position, bool enable);
 570
 571
 572         /**
 573          * Sets the text color of the button item for the specified state.
 574          *
 575          * @since               2.0
 576          *
 577          * @return      An error code
 578          * @param[in]   status          The status of the button item
 579          * @param[in]   color           The button item text color to set
 580          * @exception   E_SUCCESS       The method is successful.
 581          * @exception   E_SYSTEM        A system error has occurred.
 582          */
 583         result SetButtonTextColor(ButtonItemStatus status, const Tizen::Graphics::Color& color);
 584
 585
 586         /**
 587          * Sets the badge icon of the specified ButtonItem.
 588          *
 589          * @since               2.0
 590          *
 591          * @return              An error code
 592          * @param[in]   position                                The button item position
 593          * @param[in]   pBadgeIcon                              The bitmap for the icon
 594          * @exception   E_SUCCESS                               The method is successful.
 595          * @exception   E_UNSUPPORTED_OPERATION         This operation is not supported. @n
 596          *                                                                      The operation is not supported when the style of the %Header control is ::HEADER_STYLE_TAB @n
 597          *                                                                              or ::HEADER_STYLE_TAB_LARGE.
 598          */
 599         result SetButtonBadgeIcon(ButtonPosition position, const Tizen::Graphics::Bitmap* pBadgeIcon);
 600
 601
 602         /**
 603          * Sets the numbered badge icon of the specified ButtonItem.
 604          *
 605          * @since               2.0
 606          *
 607          * @return      An error code
 608          * @param[in]   position                        The button item position
 609          * @param[in]   number                                  The number value that should be displayed as the badge icon
 610          * @exception   E_SUCCESS                       The method is successful.
 611          * @exception   E_INVALID_ARG                           The specified @c number must be in the range defined by @c 0 and @c 99999.
 612          * @exception   E_UNSUPPORTED_OPERATION         This operation is not supported. @n
 613          *                                                                      The operation is not supported when the style of the %Header control is ::HEADER_STYLE_TAB @n
 614          *                                                                              or ::HEADER_STYLE_TAB_LARGE.
 615          * @remarks     To remove the numbered badge icon from an item, pass @c 0 as the value of @c number.
 616          */
 617         result SetButtonNumberedBadgeIcon(ButtonPosition position, int number);
 618
 619
 620         /**
 621          * Sets the contents of the %Header control item at the specified index.
 622          *
 623          * @since               2.0
 624          *
 625          * @return      An error code
 626          * @param[in]   itemIndex           The index at which to set the specified item
 627          * @param[in]   item                The item to set
 628          * @exception   E_SUCCESS           The method is successful.
 629          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the data structure. @n
 630          *                                                                      The index is greater than or equal to the number of elements or less than @c 0.
 631          * @exception   E_INVALID_ARG       A specified input parameter is invalid.
 632          * @exception   E_SYSTEM            A system error has occurred.
 633          * @remarks     The contents of the specified item are copied.
 634          */
 635         result SetItemAt(int itemIndex, const HeaderItem& item);
 636
 637
 638         /**
 639          * Sets the badge icon of the specified segmented style header item.
 640          *
 641          * @since               2.0
 642          *
 643          * @return                      An error code
 644          * @param[in]           itemIndex                               The item index
 645          * @param[in]           pBadgeIcon                              The bitmap for the icon
 646          * @exception           E_SUCCESS                               The method is successful.
 647          * @exception           E_OUT_OF_RANGE                  The specified index is outside the bounds of the data structure. @n
 648          *                                                                                      The index is greater than or equal to the number of elements or less than @c 0.
 649          * @exception           E_UNSUPPORTED_OPERATION The operation is not supported when the style of the %Header control is ::HEADER_STYLE_TITLE.
 650          * @exception           E_SYSTEM                                A system error has occurred.
 651          */
 652         result SetItemBadgeIcon(int itemIndex, const Tizen::Graphics::Bitmap* pBadgeIcon);
 653
 654
 655         /**
 656          * Sets the numbered badge icon of the specified segmented style header item.
 657          *
 658          * @since               2.0
 659          *
 660          * @return              An error code
 661          * @param[in]   itemIndex                               The item index
 662          * @param[in]   number                                  The number value that should be displayed as the badge icon
 663          * @exception   E_SUCCESS                               The method is successful.
 664          * @exception   E_INVALID_ARG                   The specified @c number must be in the range defined by @c 0 and @c 99999.
 665          * @exception   E_OUT_OF_RANGE                  The specified index is outside the bounds of the data structure. @n
 666          *                                                                              The index is greater than or equal to the number of elements or less than @c 0.
 667          * @exception   E_UNSUPPORTED_OPERATION The operation is not supported when the style of the %Header control is ::HEADER_STYLE_TITLE.
 668          * @exception   E_SYSTEM                                A system error has occurred.
 669          * @remarks             To remove the numbered badge icon from an item, pass @c 0 as the value of @c number.
 670          */
 671         result SetItemNumberedBadgeIcon(int itemIndex, int number);
 672
 673
 674         /**
 675          * Sets the item color for the specified state.
 676          *
 677          * @since       2.0
 678          *
 679          * @return              An error code
 680          * @param[in]   status          The item status
 681          * @param[in]   color           The item color to set
 682          * @exception   E_SUCCESS       The method is successful.
 683          * @exception   E_SYSTEM            A system error has occurred.
 684          * @see         GetItemColor()
 685          */
 686         result SetItemColor(HeaderItemStatus status, const Tizen::Graphics::Color& color);
 687
 688
 689         /**
 690          * Sets the item state at the specified index in the %Header control.
 691          *
 692          * @since               2.0
 693          *
 694          * @return      An error code
 695          * @param[in]   itemIndex               The index of the item to set
 696          * @param[in]   enable                 Set to @c true to enable the item state, @n
 697          *                                      else @c false
 698          * @exception   E_SUCCESS               The method is successful.
 699          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure. @n
 700          *                                                                              The index is greater than or equal to the number of elements or less than @c 0.
 701          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 702          *                                      The specified item is currently selected.
 703          * @exception   E_SYSTEM                A system error has occurred.
 704          */
 705         result SetItemEnabled(int itemIndex, bool enable);
 706
 707
 708         /**
 709          * Sets the item text color for the specified state.
 710          *
 711          * @since               2.0
 712          *
 713          * @return      An error code
 714          * @param[in]   status              The item status
 715          * @param[in]   color               The item text color to set
 716          * @exception   E_SUCCESS           The method is successful.
 717          * @exception   E_SYSTEM            A system error has occurred.
 718          */
 719         result SetItemTextColor(HeaderItemStatus status, const Tizen::Graphics::Color& color);
 720
 721
 722         /**
 723          * Sets the selected item at the specified index.
 724          *
 725          * @since               2.0
 726          *
 727          * @return      An error code
 728          * @param[in]   itemIndex               The index of the item to select
 729          * @exception   E_SUCCESS               The method is successful.
 730          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure. @n
 731          *                                                                              The index is greater than or equal to the number of elements or less than @c 0.
 732          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
 733          *                                      The item at the specified index is disabled.
 734          * @exception   E_UNSUPPORTED_OPERATION The operation is not supported when the %Header control style is ::HEADER_STYLE_TITLE, @n
 735          *                                      ::HEADER_STYLE_TITLE_BUTTON or ::HEADER_STYLE_BUTTON.
 736          * @exception   E_SYSTEM                A system error has occurred.
 737          */
 738         result SetItemSelected(int itemIndex);
 739
 740
 741         /**
 742          * Sets the color of the %Header control.
 743          *
 744          * @since               2.0
 745          *
 746          * @return      An error code
 747          * @param[in]   color               The header color
 748          * @exception   E_SUCCESS           The method is successful.
 749          */
 750         result SetColor(const Tizen::Graphics::Color& color);
 751
 752
 753         /**
 754          * Sets the style of the %Header control.
 755          *
 756          * @since               2.0
 757          *
 758          * @return      An error code
 759          * @param[in]   style                    The header style to set
 760          * @exception   E_SUCCESS                        The method is successful.
 761          * @exception   E_SYSTEM                         A system error has occurred.
 762          * @remarks             All items and buttons will be removed if the style is changed.
 763          */
 764         result SetStyle(HeaderStyle style);
 765
 766
 767         /**
 768          * Sets the title icon of the %Header control that has the title style.
 769          *
 770          * @since               2.0
 771          *
 772          * @return              An error code
 773          * @param[in]   pIcon                   The title icon to set @n
 774          *                                                                      Set to @c null to remove the title icon.
 775          * @exception   E_SUCCESS               The method is successful.
 776          * @exception   E_UNSUPPORTED_OPERATION The operation is supported when the %Header control style is ::HEADER_STYLE_TITLE, @n
 777          *                                      ::HEADER_STYLE_SEGMENTED_WITH_TITLE or ::HEADER_STYLE_TAB_WITH_TITLE.
 778          * @exception   E_SYSTEM                        A system error has occurred.
 779          */
 780         result SetTitleIcon(const Tizen::Graphics::Bitmap* pIcon);
 781
 782
 783         /**
 784          * Sets the title text of the %Header control.
 785          *
 786          * @since               2.0
 787          *
 788          * @return              An error code
 789          * @param[in]   text                        The text to set
 790          * @exception   E_SUCCESS               The method is successful.
 791          * @exception   E_UNSUPPORTED_OPERATION The operation is supported when the %Header control style is ::HEADER_STYLE_TITLE, @n
 792          *                                              ::HEADER_STYLE_SEGMENTED_WITH_TITLE or ::HEADER_STYLE_TAB_WITH_TITLE.
 793          * @exception   E_SYSTEM                        A system error has occurred.
 794          * @remarks             If the text cannot be displayed in a line, then the ellipsis is applied at the end. @n
 795          *                              When the title icon is set along with the title text, the title retains the left alignment.
 796          */
 797         result SetTitleText(const Tizen::Base::String& text);
 798
 799
 800         /**
 801          * Sets the title text color.
 802          *
 803          * @since               2.0
 804          *
 805          * @return      An error code
 806          * @param[in]   color                   The title text color to set
 807          * @exception   E_SUCCESS               The method is successful.
 808          * @exception   E_UNSUPPORTED_OPERATION The operation is supported when the %Header control style is ::HEADER_STYLE_TITLE, @n
 809          *                                      ::HEADER_STYLE_SEGMENTED_WITH_TITLE or ::HEADER_STYLE_TAB_WITH_TITLE.
 810          * @exception   E_SYSTEM                        A system error has occurred.
 811          */
 812         result SetTitleTextColor(const Tizen::Graphics::Color& color);
 813
 814
 815         /**
 816          * Sets the description text.
 817          *
 818          * @since               2.0
 819          *
 820          * @return              An error code
 821          * @param[in]   text                        The text to set
 822          * @exception   E_SUCCESS               The method is successful.
 823          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance does not support the execution of the specified operation. @n
 824          *                                      The style of the %Header control is not ::HEADER_STYLE_TITLE.
 825          * @exception   E_SYSTEM                        A system error has occurred.
 826          * @remarks             If the text cannot be displayed in a line, then the ellipsis is applied at the end. @n
 827          *                              When the title icon is set along with the title text, the title retains the left alignment.
 828          */
 829         result SetDescriptionText(const Tizen::Base::String& text);
 830
 831
 832         /**
 833          * Sets the description text color.
 834          *
 835          * @since               2.0
 836          *
 837          * @return      An error code
 838          * @param[in]   color                   The description text color to set
 839          * @exception   E_SUCCESS               The method is successful.
 840          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance does not support the execution of the specified operation. @n
 841          *                                      The style of the %Header control is not ::HEADER_STYLE_TITLE.
 842          * @exception   E_SYSTEM                        A system error has occurred.
 843          */
 844         result SetDescriptionTextColor(const Tizen::Graphics::Color& color);
 845
 846
 847         /**
 848          * Stops the waiting animation in progress at the specified position.
 849          *
 850          * @since               2.0
 851          *
 852          * @return              An error code
 853          * @param[in]   animationPos                    The waiting animation position
 854          * @exception   E_SUCCESS                               The method is successful.
 855          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 856          * @exception   E_SYSTEM                                A system error has occurred.
 857          * @remarks             This method returns @c E_INVALID_OPERATION if no waiting animation is in progress at the specified position.
 858          * @see                 GetWaitingAnimationStatus()
 859          * @see                 PauseWaitingAnimation()
 860          * @see                 PlayWaitingAnimation()
 861          */
 862         result StopWaitingAnimation(HeaderAnimationPosition animationPos);
 863
 864
 865         /**
 866          * Adds an IActionEventListener instance. @n
 867          * OnActionPerformed() of the added listener is called when the user selects an item.
 868          *
 869          * @since               2.0
 870          *
 871          * @param[in]   listener        The event listener to add
 872          */
 873         void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
 874
 875
 876         /**
 877          * Removes an IActionEventListener instance. @n
 878          * The removed listener cannot listen to events when they are fired.
 879          *
 880          * @since               2.0
 881          *
 882          * @param[in]   listener        The event listener to remove
 883          */
 884         void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
 885
 886
 887         /**
 888          * Checks whether the tab edit mode is enabled.
 889          *
 890          * @since               2.0
 891          *
 892          * @return      @c true if the tab edit mode is set, @n
 893          *                              else @c false
 894          */
 895         bool IsTabEditModeEnabled(void) const;
 896
 897
 898         /**
 899          * Enables or disables the tab edit mode.
 900          *
 901          * @since               2.0
 902          *
 903          * @return      An error code
 904          * @param[in]   enable                  Set to @c true to enable the edit mode, @n
 905          *                                      else @c false
 906          * @exception   E_SUCCESS               The method is successful.
 907          * @exception   E_UNSUPPORTED_OPERATION The operation is supported when the style of the %Header control style is ::HEADER_STYLE_TAB, @n
 908          *                                              ::HEADER_STYLE_TAB_WITH_TITLE or ::HEADER_STYLE_TAB_LARGE.
 909          */
 910         result SetTabEditModeEnabled(bool enable);
 911
 912
 913         /**
 914         * Sets the back button.
 915         *
 916         * @brief        <i> [Deprecated] </i>
 917         * @deprecated   This method is deprecated because hardware back key is mandatory for Tizen mobile devices. @n
 918         *               This method is not guaranteed to work properly.
 919         * @since                2.0
 920         *
 921         * @return       An error code
 922         * @exception    E_SUCCESS                                       The method is successful.
 923         * @exception    E_UNSUPPORTED_OPERATION         This device does not support the software back button.
 924         * @remarks      When the back button is pressed, OnFormBackRequested() of IFormBackEventListener is called.
 925         */
 926         result SetBackButton(void);
 927
 928
 929         /**
 930         * Checks whether the back button item is set.
 931         *
 932         * @brief        <i> [Deprecated] </i>
 933         * @deprecated   This method is deprecated because hardware back key is mandatory for Tizen mobile devices. @n
 934         *               This method is not guaranteed to work properly.
 935         * @since                2.0
 936         *
 937         * @return               @c true if the back button item is set, @n
 938         *               else @c false
 939         */
 940         bool IsBackButtonSet(void) const;
 941
 942
 943         /**
 944         * Removes the back button item.
 945         *
 946         * @brief        <i> [Deprecated] </i>
 947         * @deprecated   This method is deprecated because hardware back key is mandatory for Tizen mobile devices. @n
 948         *               This method is not guaranteed to work properly.
 949         * @since                2.0
 950         *
 951         */
 952         void RemoveBackButton(void);
 953
 954
 955         /**
 956         * Enables or disables the back button.
 957         *
 958         * @brief        <i> [Deprecated] </i>
 959         * @deprecated   This method is deprecated because hardware back key is mandatory for Tizen mobile devices. @n
 960         *               This method is not guaranteed to work properly.
 961         * @since                2.0
 962         *
 963         * @return       An error code
 964         * @param[in]    enable                  Set to @c true to enable the back button, @n
 965         *                                                       else @c false
 966         * @exception    E_SUCCESS               The method is successful.
 967         * @exception    E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 968         *                                               The back button item is not set.
 969         */
 970         result SetBackButtonEnabled(bool enable);
 971
 972
 973         /**
 974         * Gets the state of the back button.
 975         *
 976         * @brief        <i> [Deprecated] </i>
 977         * @deprecated   This method is deprecated because hardware back key is mandatory for Tizen mobile devices. @n
 978         *               This method is not guaranteed to work properly.
 979         * @since                2.0
 980         *
 981         * @return       The state of the back button, @n
 982         *               else @c BUTTON_ITEM_STATUS_NORMAL if an error occurs.
 983         * @exception    E_SUCCESS                       The method is successful.
 984         * @exception    E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 985         *                                                               The back button is not set.
 986         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 987         */
 988         ButtonItemStatus GetBackButtonStatus(void) const;
 989
 990
 991         /**
 992         * Gets the position and size of the specified button item.
 993         *
 994         * @since                2.0
 995         *
 996         * @return       The position and size of the button item at the specified position.
 997         * @param[in]    position                The position of the button item
 998         * @exception    E_SUCCESS               The method is successful.
 999         * @exception    E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
1000         *                                               There is no button set at the specified position.
1001         * @remarks      The specific error code can be accessed using the GetLastResult() method.
1002         */
1003         Tizen::Graphics::Rectangle GetButtonBounds(ButtonPosition position) const;
1004
1005         /**
1006         * Gets the position and size of the specified button item.
1007         *
1008         * @since                2.1
1009         *
1010         * @return       The position and size of the button item at the specified position.
1011         * @param[in]    position                The position of the button item
1012         * @exception    E_SUCCESS               The method is successful.
1013         * @exception    E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
1014         *                                               There is no button set at the specified position.
1015         * @remarks      The specific error code can be accessed using the GetLastResult() method.
1016         */
1017         Tizen::Graphics::FloatRectangle GetButtonBoundsF(ButtonPosition position) const;
1018
1019         /**
1020         * Sets the badge icon.
1021         *
1022         * @since        2.1
1023         *
1024         * @return       An error code
1025         * @param[in]    pBadgeIcon               The bitmap for the badge icon
1026         * @exception    E_SUCCESS                The method is successful.
1027         * @exception    E_INVALID_OPERATION      This operation is invalid. @n
1028         *                                        The operation is invalid when the style of the %Header control is not ::HEADER_STYLE_TITLE
1029         *                                               or ::HEADER_STYLE_SEGMENTED_WITH_TITLE or ::HEADER_STYLE_TAB_WITH_TITLE.
1030         * @remarks      For icon size details, see <a href="../org.tizen.native.appprogramming/html/guide/ui/control_iconsize.htm">here</a>.
1031         */
1032         result SetTitleBadgeIcon(const Tizen::Graphics::Bitmap* pBadgeIcon);
1033
1034         /**
1035         * Sets the numbered badge icon.
1036         *
1037         * @since        2.1
1038         *
1039         * @return       An error code
1040         * @param[in]    number                    The number value that should be displayed as the badge icon
1041         * @exception    E_SUCCESS                 The method is successful.
1042         * @exception    E_INVALID_ARG             The specified @c number must be in the range defined by @c 0 and @c 99999.
1043         * @exception    E_INVALID_OPERATION       This operation is invalid. @n
1044         *                                         The operation is invalid when the style of the %Header control is not ::HEADER_STYLE_TITLE
1045         *                                                       or ::HEADER_STYLE_SEGMENTED_WITH_TITLE TITLE or ::HEADER_STYLE_TAB_WITH_TITLE.
1046         * @remarks      To remove the numbered badge icon from an item, pass @c 0 as the value of @c number.
1047         */
1048         result SetTitleNumberedBadgeIcon(int number);
1049
1050
1051 protected:
1052         //
1053         //This method is for internal use only. Using this method can cause behavioral, security-related,
1054         //and consistency-related issues in the application.
1055         //
1056         // This is the default constructor for this class.
1057         //
1058         // @since         2.0
1059         //
1060         Header(void);
1061
1062
1063         //
1064         //This method is for internal use only. Using this method can cause behavioral, security-related,
1065         //and consistency-related issues in the application.
1066         //
1067         // This is the destructor for this class.
1068         //
1069         // @since         2.0
1070         //
1071         virtual ~Header(void);
1072
1073
1074 private:
1075         //
1076         //This method is for internal use only. Using this method can cause behavioral, security-related,
1077         //and consistency-related issues in the application.
1078         //
1079         // Initializes this instance of %Header with the specified parameter.
1080         //
1081         // @since               2.0
1082         // @return              An error code
1083         // @exception   E_SUCCESS                       The method is successful.
1084         // @exception   E_SYSTEM                        A system error has occurred.
1085         //
1086         result Construct(void);
1087
1088         Header(const Header& rhs);
1089         Header& operator =(const Header& rhs);
1090
1091 private:
1092         friend class _FormImpl;
1093         friend class _HeaderImpl;
1094
1095 };
1096
1097 }}} // Tizen::Ui::Controls
1098
1099 #endif // _FUI_CTRL_HEADER_H_