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