inc/FUiCtrlHeader.h

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