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 add
 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 insert
 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 supported when the style of the %Header control is @c HEADER_STYLE_SEGMENTED, @n
 354          *                                          @c HEADER_STYLE_SEGMENTED_WITH_TITLE, @c HEADER_STYLE_TAB or @c HEADER_STYLE_TAB_WITH_TITLE.
 355          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 356          */
 357         int GetSelectedItemIndex(void) const;
 358
 359
 360         /**
 361          * Gets the title text of the %Header control that has the title style.
 362          *
 363          * @since               2.0
 364          *
 365          * @return              The title text, @n
 366          *                              else an empty string if an error occurs
 367          * @exception   E_SUCCESS                       The method is successful.
 368          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 369          */
 370         Tizen::Base::String GetTitleText(void) const;
 371
 372
 373         /**
 374          * Gets the title text color of the %Header control that has the title style.
 375          *
 376          * @since               2.0
 377          *
 378          * @return              The title text color, @n
 379          *                              else RGBA (0,0,0,0) if an error occurs
 380          * @exception   E_SUCCESS                       The method is successful.
 381          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 382          */
 383         Tizen::Graphics::Color GetTitleTextColor(void) const;
 384
 385
 386         /**
 387          * Gets the color of the %Header control.
 388          *
 389          * @since               2.0
 390          *
 391          * @return              The header color, @n
 392          *                              else RGBA (0,0,0,0) if an error occurs
 393          * @exception   E_SUCCESS                       The method is successful.
 394          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 395          */
 396         Tizen::Graphics::Color GetColor(void) const;
 397
 398
 399         /**
 400          * Gets the status of the waiting animation at the specified position.
 401          *
 402          * @since               2.0
 403          *
 404          * @return              The animation status
 405          * @param[in]   animationPos            The waiting animation position
 406          * @exception   E_SUCCESS                       The method is successful.
 407          * @remarks             The specific error code can be accessed using the GetLastResult() method. @n
 408          *              This method returns @c ANIMATION_STOPPED, if no animation is in progress at the specified position.
 409          * @see                 PauseWaitingAnimation()
 410          * @see                 PlayWaitingAnimation()
 411          * @see                 StopWaitingAnimation()
 412          */
 413         AnimationStatus GetWaitingAnimationStatus(HeaderAnimationPosition animationPos) const;
 414
 415
 416         /**
 417          * Pauses the waiting animation at the specified position.
 418          *
 419          * @since               2.0
 420          *
 421          * @return              An error code
 422          * @param[in]   animationPos                    The waiting animation position
 423          * @exception   E_SUCCESS                               The method is successful.
 424          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
 425          *                                                                              No waiting animation is in progress at the specified position.
 426          * @exception   E_SYSTEM                                A system error has occurred.
 427          * @see                 PlayWaitingAnimation()
 428          * @see                 StopWaitingAnimation()
 429          */
 430         result PauseWaitingAnimation(HeaderAnimationPosition animationPos);
 431
 432
 433         /**
 434          * Starts the waiting animation at the specified position.
 435          *
 436          * @since               2.0
 437          *
 438          * @return              An error code
 439          * @param[in]   animationPos                    The waiting animation position
 440          * @exception   E_SUCCESS                               The method is successful.
 441          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
 442          *                                                                              There is no button set at the specified position (except for @c HEADER_ANIMATION_POSITION_TITLE).
 443          * @exception   E_SYSTEM                                A system error has occurred.
 444          * @see                 SetButton()
 445          * @see                 IsButtonSet()
 446          * @see                 GetWaitingAnimationStatus()
 447          * @see                 PauseWaitingAnimation()
 448          * @see                 StopWaitingAnimation()
 449          */
 450         result PlayWaitingAnimation(HeaderAnimationPosition animationPos);
 451
 452
 453         /**
 454          * Removes all the button items.
 455          *
 456          * @since               2.0
 457          *
 458          * @return      An error code
 459          * @exception   E_SUCCESS       The method is successful.
 460          * @exception   E_SYSTEM        A system error has occurred.
 461          */
 462         result RemoveAllButtons(void);
 463
 464
 465         /**
 466          * Removes all the %Header control items.
 467          *
 468          * @since               2.0
 469          *
 470          * @return              An error code
 471          * @exception   E_SUCCESS                       The method is successful.
 472          * @exception   E_SYSTEM                        A system error has occurred.
 473          * @remarks             The left button, right button, and back button items are not removed.
 474          */
 475         result RemoveAllItems(void);
 476
 477
 478         /**
 479          * Removes the item at the specified index.
 480          *
 481          * @since               2.0
 482          *
 483          * @return              An error code
 484          * @param[in]   itemIndex                       The index of the item to remove
 485          * @exception   E_SUCCESS                       The method is successful.
 486          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure. @n
 487          *                                                                      The index is greater than or equal to the number of elements or less than @c 0.
 488          * @exception   E_SYSTEM            A system error has occurred.
 489          */
 490         result RemoveItemAt(int itemIndex);
 491
 492
 493         /**
 494          * Removes the button item at the specified position.
 495          *
 496          * @since               2.0
 497          *
 498          * @return      An error code
 499          * @param[in]   position        The position of the button item to remove
 500          * @exception   E_SUCCESS       The method is successful.
 501          * @exception   E_SYSTEM        A system error has occurred.
 502          * @remarks     If no button item is set at the specified position, the method returns @c E_SUCCESS.
 503          */
 504         result RemoveButtonAt(ButtonPosition position);
 505
 506
 507         /**
 508          * Sets the background bitmap image.
 509          *
 510          * @since               2.0
 511          *
 512          * @return      An error code
 513          * @param[in]   pBitmap                         The background image
 514          * @exception   E_SUCCESS                       The method is successful.
 515          * @exception   E_SYSTEM                        A system error has occurred.
 516          */
 517         result SetBackgroundBitmap(const Tizen::Graphics::Bitmap* pBitmap);
 518
 519
 520         /**
 521          * Sets the button item at the specified position.
 522          *
 523          * @since               2.0
 524          *
 525          * @return      An error code
 526          * @param[in]   position                        The position at which to set the specified button item
 527          * @param[in]   button                          The button item to set
 528          * @exception   E_SUCCESS                       The method is successful.
 529          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 530          *                                                                      The specified item is not constructed.
 531          * @exception   E_SYSTEM                        A system error has occurred.
 532          * @remarks     If there is an existing button item at the specified position, it is replaced with a new item. @n
 533          *              The contents of the specified item are copied.
 534          */
 535         result SetButton(ButtonPosition position, const ButtonItem& button);
 536
 537
 538         /**
 539          * Sets the button item color for the specified state.
 540          *
 541          * @since               2.0
 542          *
 543          * @return              An error code
 544          * @param[in]   status          The status of the button item
 545          * @param[in]   color           The button item color to set
 546          * @exception   E_SUCCESS       The method is successful.
 547          * @exception   E_SYSTEM            A system error has occurred.
 548          * @see         GetButtonColor()
 549          */
 550         result SetButtonColor(ButtonItemStatus status, const Tizen::Graphics::Color& color);
 551
 552
 553         /**
 554          * Enables or disables the button item at the specified position.
 555          *
 556          * @since       2.0
 557          *
 558          * @return      An error code
 559          * @param[in]   position                        The button item position
 560          * @param[in]   enable                          Set to @c true to enable the specified button item, @n
 561          *                                                                      else @c false to disable
 562          * @exception   E_SUCCESS                       The method is successful.
 563          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 564          *                                                                      There is no button set at the specified position.
 565          * @exception   E_SYSTEM            A system error has occurred.
 566          */
 567         result SetButtonEnabled(ButtonPosition position, bool enable);
 568
 569
 570         /**
 571          * Sets the text color of the button item for the specified state.
 572          *
 573          * @since               2.0
 574          *
 575          * @return      An error code
 576          * @param[in]   status          The status of the button item
 577          * @param[in]   color           The button item text color to set
 578          * @exception   E_SUCCESS       The method is successful.
 579          * @exception   E_SYSTEM        A system error has occurred.
 580          */
 581         result SetButtonTextColor(ButtonItemStatus status, const Tizen::Graphics::Color& color);
 582
 583
 584         /**
 585          * Sets the badge icon of the specified ButtonItem.
 586          *
 587          * @since               2.0
 588          *
 589          * @return              An error code
 590          * @param[in]   position                                The button item position
 591          * @param[in]   pBadgeIcon                              The bitmap for the icon
 592          * @exception   E_SUCCESS                               The method is successful.
 593          * @exception   E_UNSUPPORTED_OPERATION         This operation is not supported. @n
 594          *              The operation is not supported when the style of the %Header control is @c HEADER_STYLE_TAB or @c HEADER_STYLE_TAB_WITH_TITLE.
 595          */
 596         result SetButtonBadgeIcon(ButtonPosition position, const Tizen::Graphics::Bitmap* pBadgeIcon);
 597
 598
 599         /**
 600          * Sets the numbered badge icon of the specified ButtonItem.
 601          *
 602          * @since               2.0
 603          *
 604          * @return      An error code
 605          * @param[in]   position                        The button item position
 606          * @param[in]   number                                  The number value that should be displayed as the badge icon
 607          * @exception   E_SUCCESS                       The method is successful.
 608          * @exception   E_INVALID_ARG                           The specified @c number must be in the range defined by @c 0 and @c 99999.
 609          * @exception   E_UNSUPPORTED_OPERATION         This operation is not supported. @n
 610          *              The operation is not supported when the style of the %Header control is @c HEADER_STYLE_TAB or @c HEADER_STYLE_TAB_WITH_TITLE.
 611          * @remarks     To remove the numbered badge icon from an item, pass @c 0 as the value of @c number.
 612          */
 613         result SetButtonNumberedBadgeIcon(ButtonPosition position, int number);
 614
 615
 616         /**
 617          * Sets the contents of the %Header control item at the specified index.
 618          *
 619          * @since               2.0
 620          *
 621          * @return      An error code
 622          * @param[in]   itemIndex           The index at which to set the specified item
 623          * @param[in]   item                The item to set
 624          * @exception   E_SUCCESS           The method is successful.
 625          * @exception   E_OUT_OF_RANGE      The specified index is outside the bounds of the data structure. @n
 626          *                                                                      The index is greater than or equal to the number of elements or less than @c 0.
 627          * @exception   E_INVALID_ARG       A specified input parameter is invalid.
 628          * @exception   E_SYSTEM            A system error has occurred.
 629          * @remarks     The contents of the specified item are copied.
 630          */
 631         result SetItemAt(int itemIndex, const HeaderItem& item);
 632
 633
 634         /**
 635          * Sets the badge icon of the specified segmented style header item.
 636          *
 637          * @since               2.0
 638          *
 639          * @return                      An error code
 640          * @param[in]           itemIndex                               The item index
 641          * @param[in]           pBadgeIcon                              The bitmap for the icon
 642          * @exception           E_SUCCESS                               The method is successful.
 643          * @exception           E_OUT_OF_RANGE                  The specified index is outside the bounds of the data structure. @n
 644          *                                                                                      The index is greater than or equal to the number of elements or less than @c 0.
 645          * @exception           E_UNSUPPORTED_OPERATION The operation is not supported when the style of the %Header control is @c HEADER_STYLE_TITLE.
 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 The operation is not supported when the style of the %Header control is @c HEADER_STYLE_TITLE.
 664          * @exception   E_SYSTEM                                A system error has occurred.
 665          * @remarks             To remove the numbered badge icon from an item, pass @c 0 as the value of @c number.
 666          */
 667         result SetItemNumberedBadgeIcon(int itemIndex, int number);
 668
 669
 670         /**
 671          * Sets the item color for the specified state.
 672          *
 673          * @since       2.0
 674          *
 675          * @return              An error code
 676          * @param[in]   status          The item status
 677          * @param[in]   color           The item color to set
 678          * @exception   E_SUCCESS       The method is successful.
 679          * @exception   E_SYSTEM            A system error has occurred.
 680          * @see         GetItemColor()
 681          */
 682         result SetItemColor(HeaderItemStatus status, const Tizen::Graphics::Color& color);
 683
 684
 685         /**
 686          * Sets the item state at the specified index in the %Header control.
 687          *
 688          * @since               2.0
 689          *
 690          * @return      An error code
 691          * @param[in]   itemIndex               The index of the item to set
 692          * @param[in]   enable                 Set to @c true to enable the item state, @n
 693          *                                      else @c false
 694          * @exception   E_SUCCESS               The method is successful.
 695          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure. @n
 696          *                                                                              The index is greater than or equal to the number of elements or less than @c 0.
 697          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 698          *                                      The specified item is currently selected.
 699          * @exception   E_SYSTEM                A system error has occurred.
 700          */
 701         result SetItemEnabled(int itemIndex, bool enable);
 702
 703
 704         /**
 705          * Sets the item text color for the specified state.
 706          *
 707          * @since               2.0
 708          *
 709          * @return      An error code
 710          * @param[in]   status              The item status
 711          * @param[in]   color               The item text color to set
 712          * @exception   E_SUCCESS           The method is successful.
 713          * @exception   E_SYSTEM            A system error has occurred.
 714          */
 715         result SetItemTextColor(HeaderItemStatus status, const Tizen::Graphics::Color& color);
 716
 717
 718         /**
 719          * Sets the selected item at the specified index.
 720          *
 721          * @since               2.0
 722          *
 723          * @return      An error code
 724          * @param[in]   itemIndex               The index of the item to select
 725          * @exception   E_SUCCESS               The method is successful.
 726          * @exception   E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure. @n
 727          *                                                                              The index is greater than or equal to the number of elements or less than @c 0.
 728          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
 729          *                                      The item at the specified index is disabled.
 730          * @exception   E_UNSUPPORTED_OPERATION The operation is not supported when the %Header control style is @c HEADER_STYLE_TITLE, @n
 731          *                                      @c HEADER_STYLE_TITLE_BUTTON or @c HEADER_STYLE_BUTTON.
 732          * @exception   E_SYSTEM                A system error has occurred.
 733          */
 734         result SetItemSelected(int itemIndex);
 735
 736
 737         /**
 738          * Sets the color of the %Header control.
 739          *
 740          * @since               2.0
 741          *
 742          * @return      An error code
 743          * @param[in]   color               The header color
 744          * @exception   E_SUCCESS           The method is successful.
 745          */
 746         result SetColor(const Tizen::Graphics::Color& color);
 747
 748
 749         /**
 750          * Sets the style of the %Header control.
 751          *
 752          * @since               2.0
 753          *
 754          * @return      An error code
 755          * @param[in]   style                    The header style to set
 756          * @exception   E_SUCCESS                        The method is successful.
 757          * @exception   E_SYSTEM                         A system error has occurred.
 758          * @remarks             All items and buttons will be removed if the style is changed.
 759          */
 760         result SetStyle(HeaderStyle style);
 761
 762
 763         /**
 764          * Sets the title icon of the %Header control that has the title style.
 765          *
 766          * @since               2.0
 767          *
 768          * @return              An error code
 769          * @param[in]   pIcon                   The title icon to set @n
 770          *                                                                      Set to @c null to remove the title icon.
 771          * @exception   E_SUCCESS               The method is successful.
 772          * @exception   E_UNSUPPORTED_OPERATION The operation is supported when the %Header control style is @c HEADER_STYLE_TITLE, @n
 773          *                                      @c HEADER_STYLE_SEGMENTED_WITH_TITLE or @c HEADER_STYLE_TAB_WITH_TITLE.
 774          * @exception   E_SYSTEM                        A system error has occurred.
 775          */
 776         result SetTitleIcon(const Tizen::Graphics::Bitmap* pIcon);
 777
 778
 779         /**
 780          * Sets the title text of the %Header control.
 781          *
 782          * @since               2.0
 783          *
 784          * @return              An error code
 785          * @param[in]   text                        The text to set
 786          * @exception   E_SUCCESS               The method is successful.
 787          * @exception   E_UNSUPPORTED_OPERATION The operation is supported when the %Header control style is @c HEADER_STYLE_TITLE, @n
 788          *                                              @c HEADER_STYLE_SEGMENTED_WITH_TITLE or @c HEADER_STYLE_TAB_WITH_TITLE.
 789          * @exception   E_SYSTEM                        A system error has occurred.
 790          * @remarks             If the text cannot be displayed in a line, then the ellipsis is applied at the end. @n
 791          *                              When the title icon is set along with the title text, the title retains the left alignment.
 792          */
 793         result SetTitleText(const Tizen::Base::String& text);
 794
 795
 796         /**
 797          * Sets the title text color.
 798          *
 799          * @since               2.0
 800          *
 801          * @return      An error code
 802          * @param[in]   color                   The title text color to set
 803          * @exception   E_SUCCESS               The method is successful.
 804          * @exception   E_UNSUPPORTED_OPERATION The operation is supported when the %Header control style is @c HEADER_STYLE_TITLE, @n
 805          *                                      @c HEADER_STYLE_SEGMENTED_WITH_TITLE or @c HEADER_STYLE_TAB_WITH_TITLE.
 806          * @exception   E_SYSTEM                        A system error has occurred.
 807          */
 808         result SetTitleTextColor(const Tizen::Graphics::Color& color);
 809
 810
 811         /**
 812          * Sets the description text.
 813          *
 814          * @since               2.0
 815          *
 816          * @return              An error code
 817          * @param[in]   text                        The text to set
 818          * @exception   E_SUCCESS               The method is successful.
 819          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance does not support the execution of the specified operation. @n
 820          *                                      The style of the %Header control is not @c HEADER_STYLE_TITLE.
 821          * @exception   E_SYSTEM                        A system error has occurred.
 822          * @remarks             If the text cannot be displayed in a line, then the ellipsis is applied at the end. @n
 823          *                              When the title icon is set along with the title text, the title retains the left alignment.
 824          */
 825         result SetDescriptionText(const Tizen::Base::String& text);
 826
 827
 828         /**
 829          * Sets the description text color.
 830          *
 831          * @since               2.0
 832          *
 833          * @return      An error code
 834          * @param[in]   color                   The description text color to set
 835          * @exception   E_SUCCESS               The method is successful.
 836          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance does not support the execution of the specified operation. @n
 837          *                                      The style of the %Header control is not @c HEADER_STYLE_TITLE.
 838          * @exception   E_SYSTEM                        A system error has occurred.
 839          */
 840         result SetDescriptionTextColor(const Tizen::Graphics::Color& color);
 841
 842
 843         /**
 844          * Stops the waiting animation in progress at the specified position.
 845          *
 846          * @since               2.0
 847          *
 848          * @return              An error code
 849          * @param[in]   animationPos                    The waiting animation position
 850          * @exception   E_SUCCESS                               The method is successful.
 851          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 852          * @exception   E_SYSTEM                                A system error has occurred.
 853          * @remarks             This method returns @c E_INVALID_OPERATION if no waiting animation is in progress at the specified position.
 854          * @see                 GetWaitingAnimationStatus()
 855          * @see                 PauseWaitingAnimation()
 856          * @see                 PlayWaitingAnimation()
 857          */
 858         result StopWaitingAnimation(HeaderAnimationPosition animationPos);
 859
 860
 861         /**
 862          * Adds an IActionEventListener instance. @n
 863          * OnActionPerformed() of the added listener is called when the user selects an item.
 864          *
 865          * @since               2.0
 866          *
 867          * @param[in]   listener        The event listener to add
 868          */
 869         void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
 870
 871
 872         /**
 873          * Removes an IActionEventListener instance. @n
 874          * The removed listener cannot listen to events when they are fired.
 875          *
 876          * @since               2.0
 877          *
 878          * @param[in]   listener        The event listener to remove
 879          */
 880         void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
 881
 882
 883         /**
 884          * Checks whether the tab edit mode is enabled.
 885          *
 886          * @since               2.0
 887          *
 888          * @return      @c true if the tab edit mode is set, @n
 889          *                              else @c false
 890          */
 891         bool IsTabEditModeEnabled(void) const;
 892
 893
 894         /**
 895          * Enables or disables the tab edit mode.
 896          *
 897          * @since               2.0
 898          *
 899          * @return      An error code
 900          * @param[in]   enable                  Set to @c true to enable the edit mode, @n
 901          *                                      else @c false
 902          * @exception   E_SUCCESS               The method is successful.
 903          * @exception   E_UNSUPPORTED_OPERATION The operation is supported when the style of the %Header control style is @c HEADER_STYLE_TAB @n
 904          *                                      or @c HEADER_STYLE_TAB_WITH_TITLE.
 905          */
 906         result SetTabEditModeEnabled(bool enable);
 907
 908
 909         /**
 910         * Sets the back button.
 911         *
 912         * @since                2.0
 913         *
 914         * @return       An error code
 915         * @exception    E_SUCCESS                                       The method is successful.
 916         * @exception    E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
 917         *                                           There are more than 2 header items.
 918         * @exception    E_UNSUPPORTED_OPERATION         The operation is supported when the style of the %Header control is @c HEADER_STYLE_BUTTON. @n
 919         *                                               This device does not support the software back button.
 920         * @remarks      When the back button is pressed, OnFormBackRequested() of IFormBackEventListener is called. @n
 921         *               If the right button is already set, then the button is replaced with the back button.
 922         */
 923         result SetBackButton(void);
 924
 925
 926         /**
 927         * Checks whether the back button item is set.
 928         *
 929         * @since                2.0
 930         *
 931         * @return               @c true if the back button item is set, @n
 932         *               else @c false
 933         */
 934         bool IsBackButtonSet(void) const;
 935
 936
 937         /**
 938         * Removes the back button item.
 939         *
 940         * @since                2.0
 941         *
 942         */
 943         void RemoveBackButton(void);
 944
 945
 946         /**
 947         * Enables or disables the back button.
 948         *
 949         * @since                2.0
 950         *
 951         * @return       An error code
 952         * @param[in]    enable                  Set to @c true to enable the back button, @n
 953         *                                                       else @c false
 954         * @exception    E_SUCCESS               The method is successful.
 955         * @exception    E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 956         *                                               The back button item is not set.
 957         */
 958         result SetBackButtonEnabled(bool enable);
 959
 960
 961         /**
 962         * Gets the state of the back button.
 963         *
 964         * @since                2.0
 965         *
 966         * @return       The state of the back button, @n
 967         *               else @c BUTTON_ITEM_STATUS_NORMAL if an error occurs.
 968         * @exception    E_SUCCESS                       The method is successful.
 969         * @exception    E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 970         *                                                               The back button is not set.
 971         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 972         */
 973         ButtonItemStatus GetBackButtonStatus(void) const;
 974
 975
 976         /**
 977         * Gets the position and size of the specified button item.
 978         *
 979         * @since                2.0
 980         *
 981         * @return       The position and size of the button item at the specified position.
 982         * @param[in]    position                The position of the button item
 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         *                                               There is no button set at the specified position.
 986         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 987         */
 988         Tizen::Graphics::Rectangle GetButtonBounds(ButtonPosition position) const;
 989
 990         /**
 991         * Gets the position and size of the specified button item.
 992         *
 993         * @since                2.1
 994         *
 995         * @return       The position and size of the button item at the specified position.
 996         * @param[in]    position                The position of the button item
 997         * @exception    E_SUCCESS               The method is successful.
 998         * @exception    E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 999         *                                               There is no button set at the specified position.
1000         * @remarks      The specific error code can be accessed using the GetLastResult() method.
1001         */
1002         Tizen::Graphics::FloatRectangle GetButtonBoundsF(ButtonPosition position) const;
1003
1004         /**
1005         * Sets the badge icon.
1006         *
1007         * @since        2.1
1008         *
1009         * @return       An error code
1010         * @param[in]    pBadgeIcon               The bitmap for the badge icon
1011         * @exception    E_SUCCESS                The method is successful.
1012         * @exception    E_INVALID_OPERATION      This operation is invalid. @n
1013         *                                        The operation is invalid when the style of the %Header control is not @c HEADER_STYLE_TITLE or @c HEADER_STYLE_SEGMENTED_WITH_TITLE or @c HEADER_STYLE_TAB_WITH_TITLE.
1014         * @remarks      For icon size details, see <a href="../org.tizen.native.appprogramming/html/guide/ui/control_icon_size.htm">here</a>.
1015         */
1016         result SetTitleBadgeIcon(const Tizen::Graphics::Bitmap* pBadgeIcon);
1017
1018         /**
1019         * Sets the numbered badge icon.
1020         *
1021         * @since        2.1
1022         *
1023         * @return       An error code
1024         * @param[in]    number                    The number value that should be displayed as the badge icon
1025         * @exception    E_SUCCESS                 The method is successful.
1026         * @exception    E_INVALID_ARG             The specified @c number must be in the range defined by @c 0 and @c 99999.
1027         * @exception    E_INVALID_OPERATION       This operation is invalid. @n
1028         *                                         The operation is invalid when the style of the %Header control is not @c HEADER_STYLE_TITLE or @c HEADER_STYLE_SEGMENTED_WITH_TITLE TITLE or @c HEADER_STYLE_TAB_WITH_TITLE.
1029         * @remarks      To remove the numbered badge icon from an item, pass @c 0 as the value of @c number.
1030         */
1031         result SetTitleNumberedBadgeIcon(int number);
1032
1033
1034 protected:
1035         //
1036         //This method is for internal use only. Using this method can cause behavioral, security-related,
1037         //and consistency-related issues in the application.
1038         //
1039         // This is the default constructor for this class.
1040         //
1041         // @since         2.0
1042         //
1043         Header(void);
1044
1045
1046         //
1047         //This method is for internal use only. Using this method can cause behavioral, security-related,
1048         //and consistency-related issues in the application.
1049         //
1050         // This is the destructor for this class.
1051         //
1052         // @since         2.0
1053         //
1054         virtual ~Header(void);
1055
1056
1057 private:
1058         //
1059         //This method is for internal use only. Using this method can cause behavioral, security-related,
1060         //and consistency-related issues in the application.
1061         //
1062         // Initializes this instance of %Header with the specified parameter.
1063         //
1064         // @since               2.0
1065         // @return              An error code
1066         // @exception   E_SUCCESS                       The method is successful.
1067         // @exception   E_SYSTEM                        A system error has occurred.
1068         //
1069         result Construct(void);
1070
1071         Header(const Header& rhs);
1072         Header& operator =(const Header& rhs);
1073
1074 private:
1075         friend class _FormImpl;
1076         friend class _HeaderImpl;
1077
1078 };
1079
1080 }}} // Tizen::Ui::Controls
1081
1082 #endif // _FUI_CTRL_HEADER_H_