inc/FUiCtrlTabBar.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  * @file    FUiCtrlTabBar.h
  19  * @brief   This is the header file for the %TabBar class.
  20  *
  21  * This header file contains the declarations of the %TabBar class.
  22  */
  23 #ifndef _FUI_CTRL_TAB_BAR_H_
  24 #define _FUI_CTRL_TAB_BAR_H_
  25
  26 #include <FUiControl.h>
  27
  28 namespace Tizen { namespace Ui
  29 {
  30 class IActionEventListener;
  31 }} // Tizen::Ui
  32 namespace Tizen { namespace Ui { namespace Controls
  33 {
  34 class TabBarItem;
  35 }}} // Tizen::Ui::Controls
  36
  37 namespace Tizen { namespace Ui { namespace Controls
  38 {
  39 /**
  40  * @enum        TabBarItemStatus
  41  *
  42  * Defines the possible states of TabBarItem.
  43  *
  44  * @since   2.0
  45  */
  46 enum TabBarItemStatus
  47 {
  48         TAB_BAR_ITEM_STATUS_NORMAL,             /**< The normal state */
  49         TAB_BAR_ITEM_STATUS_SELECTED            /**< The selected state */
  50 };
  51
  52
  53 /**
  54  * @class   TabBar
  55  * @brief   This class is an implementation of %TabBar.
  56  *
  57  * @since   2.0
  58  *
  59  * The %TabBar class displays a list of possible options for the user selection in a horizontal list.
  60  *
  61  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_tab_bar.htm">TabBar</a>.
  62  *
  63  * The following example demonstrates how to use the %TabBar class.
  64  *
  65  * @code
  66 // Sample code for TabBarSample.h
  67 #include <FUi.h>
  68
  69 class TabBarSample
  70         : public Tizen::Ui::Controls::Form
  71         , public Tizen::Ui::IActionEventListener
  72 {
  73 public:
  74         TabBarSample(void)
  75         : __pTabBar(null){}
  76
  77         bool Initialize(void);
  78         virtual result OnInitializing(void);
  79
  80         // IActionEventListener
  81         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
  82
  83 private:
  84         static const int ID_TABBAR_ITEM1 = 100;
  85         static const int ID_TABBAR_ITEM2 = 101;
  86         static const int ID_TABBAR_ITEM3 = 102;
  87
  88         Tizen::Ui::Controls::TabBar *__pTabBar;
  89 };
  90  *      @endcode
  91  *
  92  *      @code
  93 // Sample code for TabBarSample.cpp
  94 #include "TabBarSample.h"
  95
  96 using namespace Tizen::Ui::Controls;
  97
  98 bool
  99 TabBarSample::Initialize(void)
 100 {
 101         Construct(FORM_STYLE_NORMAL);
 102         return true;
 103 }
 104
 105 result
 106 TabBarSample::OnInitializing()
 107 {
 108         result r = E_SUCCESS;
 109
 110         // Creates an instance of TabBar
 111         __pTabBar = new TabBar();
 112         __pTabBar->Construct(0, 0, GetClientAreaBounds().width);
 113
 114         // Creates instances of TabBarItem
 115          TabBarItem tabBarItem1;
 116          TabBarItem tabBarItem2;
 117          TabBarItem tabBarItem3;
 118
 119          tabBarItem1.Construct(L"1", ID_TABBAR_ITEM1);
 120          tabBarItem2.Construct(L"2", ID_TABBAR_ITEM2);
 121          tabBarItem3.Construct(L"3", ID_TABBAR_ITEM3);
 122
 123          // Adds items to the tab bar
 124         __pTabBar->AddItem(tabBarItem1);
 125         __pTabBar->AddItem(tabBarItem2);
 126         __pTabBar->AddItem(tabBarItem3);
 127         __pTabBar->AddActionEventListener(*this);
 128
 129         // Adds the tab bar to the form
 130         AddControl(*__pTabBar);
 131
 132         return r;
 133 }
 134
 135 // IActionEventListener implementation
 136 void
 137 TabBarSample::OnActionPerformed(const Control& source, int actionId)
 138 {
 139         switch (actionId)
 140         {
 141         case ID_TABBAR_ITEM1:
 142                 {
 143                         // ....
 144                 }
 145                 break;
 146         case ID_TABBAR_ITEM2:
 147                 {
 148                         // ....
 149                 }
 150                 break;
 151         default:
 152                 break;
 153         }
 154 }
 155  * @endcode
 156  *
 157  */
 158 class _OSP_EXPORT_ TabBar
 159         : public Tizen::Ui::Control
 160 {
 161 // Lifecycle
 162 public:
 163         /**
 164          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 165          *
 166          * @since       2.0
 167          *
 168          */
 169         TabBar(void);
 170
 171
 172         /**
 173          * This destructor overrides Tizen::Base::Object::~Object().
 174          *
 175          * @since       2.0
 176          *
 177          */
 178         virtual ~TabBar(void);
 179
 180         /**
 181          * Initializes this instance of %TabBar with the specified parameters.
 182          *
 183          * @since       2.0
 184          *
 185          * @return      An error code
 186          * @param[in]   x                       The X position of the top left corner
 187          * @param[in]   y                       The Y position of the top left corner
 188          * @param[in]   width                   The width
 189          * @exception   E_SUCCESS               The method is successful.
 190          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 191          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 192          * @exception   E_SYSTEM                A system error has occurred.
 193          */
 194         result Construct(int x, int y, int width);
 195
 196         /**
 197          * Initializes this instance of %TabBar with the specified parameters.
 198          *
 199          * @since       2.1
 200          *
 201          * @return      An error code
 202          * @param[in]   x                       The X position of the top left corner
 203          * @param[in]   y                       The Y position of the top left corner
 204          * @param[in]   width                   The width
 205          * @exception   E_SUCCESS               The method is successful.
 206          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 207          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 208          * @exception   E_SYSTEM                A system error has occurred.
 209          */
 210         result Construct(float x, float y, float width);
 211
 212
 213 // Operation
 214 public:
 215         /**
 216          * Adds the specified item.
 217          *
 218          * @since       2.0
 219          *
 220          * @return      An error code
 221          * @param[in]   item                    The item to add
 222          * @exception   E_SUCCESS               The method is successful.
 223          * @exception   E_INVALID_ARG           The specified input parameter is invalid. @n
 224          *                                                                      The specified @c item is not constructed.
 225          * @exception   E_MAX_EXCEEDED          The number of items has exceeded the maximum limit.
 226          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 227          * @exception   E_SYSTEM                A system error has occurred.
 228          * @remarks             The maximum number of items for a %TabBar control is @c 100. @n
 229          *              However, the content of the specified item is copied to the %TabBar control. @n
 230          *              The item can be deallocated explicitly after this method call if it is created dynamically. @n
 231          *              The %TabBar control does not throw any exception even though the same action ID is assigned to multiple items.
 232          */
 233         result AddItem(const TabBarItem& item);
 234
 235
 236         /**
 237          * Inserts the %TabBar item at the specified index.
 238          *
 239          * @since       2.0
 240          *
 241          * @return      An error code
 242          * @param[in]   index                   The index of the item to insert
 243          * @param[in]   item                    The item to insert
 244          * @exception   E_SUCCESS               The method is successful.
 245          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 246          *                                                                      The specified @c item is not constructed.
 247          * @exception   E_MAX_EXCEEDED          The number of items has exceeded the maximum limit.
 248          * @exception   E_OUT_OF_RANGE          The specified @c index is out of the range of the data structure. @n
 249          *                                                                      The specified @c index is either greater than or equal to the number of items or is less than @c 0.
 250          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 251          * @exception   E_SYSTEM                A system error has occurred.
 252          * @remarks     The maximum number of items for a %TabBar control is @c 100. @n
 253          *              However, the content of the specified item is copied to the @c %TabBar control. @n
 254          *              The item can be deallocated explicitly after this method call if it is created dynamically. @n
 255          *              The %TabBar control does not throw any exception even though the same action ID is assigned to multiple items.
 256          */
 257         result InsertItemAt(int index, const TabBarItem& item);
 258
 259
 260         /**
 261          * Gets the color of the %TabBar control.
 262          *
 263          * @since       2.0
 264          *
 265          * @return      The color, @n
 266          *                              else RGBA(0,0,0,0) if an error occurs
 267          * @exception   E_SUCCESS           The method is successful.
 268          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 269          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 270          */
 271         Tizen::Graphics::Color GetColor(void) const;
 272
 273
 274         /**
 275          * Gets the item count.
 276          *
 277          * @since       2.0
 278          *
 279          * @return      The item count, @n
 280          *              else @c -1 if an error occurs
 281          * @exception   E_SUCCESS           The method is successful.
 282          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 283          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 284          */
 285         int GetItemCount(void) const;
 286
 287
 288         /**
 289          * Gets the item color that is displayed when an item is selected.
 290          *
 291          * @since       2.0
 292          *
 293          * @return      The selected item color, @n
 294          *                              else RGBA(0,0,0,0) if an error occurs
 295          * @exception   E_SUCCESS           The method is successful.
 296          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 297          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 298          */
 299         Tizen::Graphics::Color GetSelectedItemColor(void) const;
 300
 301
 302         /**
 303          * Gets the item text color for the specified state.
 304          *
 305          * @since       2.0
 306          *
 307          * @return      The item text color, @n
 308          *                              else RGBA (0,0,0,0) if an error occurs
 309          * @param[in]   status              The item state
 310          * @exception   E_SUCCESS           The method is successful.
 311          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 312          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 313          */
 314         Tizen::Graphics::Color GetItemTextColor(TabBarItemStatus status) const;
 315
 316
 317         /**
 318          * Gets the index of the selected item.
 319          *
 320          * @since       2.0
 321          *
 322          * @return      The selected item index, @n
 323          *              else @c -1 if an error occurs
 324          * @exception   E_SUCCESS               The method is successful.
 325          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 326          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 327          */
 328         int GetSelectedItemIndex(void) const;
 329
 330
 331         /**
 332          * Removes the %TabBar item at the specified index.
 333          *
 334          * @since       2.0
 335          *
 336          * @return      An error code
 337          * @param[in]   index                   The index of the item
 338          * @exception   E_SUCCESS               The method is successful.
 339          * @exception   E_OUT_OF_RANGE          The specified @c index is out of the range of the data structure. @n
 340          *                                                                      The specified @c index is either greater than or equal to the number of items or is less than @c 0.
 341          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 342          * @exception   E_SYSTEM                A system error has occurred.
 343          * @remarks     If the currently selected item is removed, the next item is selected automatically.
 344          */
 345         result RemoveItemAt(int index);
 346
 347
 348         /**
 349          * Removes all the items from the %TabBar control.
 350          *
 351          * @since       2.0
 352          *
 353          * @return      An error code
 354          * @exception   E_SUCCESS         The method is successful.
 355          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 356          * @exception   E_SYSTEM          A system error has occurred.
 357          */
 358         result RemoveAllItems(void);
 359
 360
 361         /**
 362          * Sets the color of the %TabBar control.
 363          *
 364          * @since       2.0
 365          *
 366          * @return      An error code
 367          * @param[in]   color             The color
 368          * @exception   E_SUCCESS         The method is successful.
 369          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 370          */
 371         result SetColor(const Tizen::Graphics::Color& color);
 372
 373
 374         /**
 375          * Sets the content of the %TabBar item at the specified index.
 376          *
 377          * @since       2.0
 378          *
 379          * @return      An error code
 380          * @param[in]   index                   The index at which to set the specified item
 381          * @param[in]   item                    The item to set
 382          * @exception   E_SUCCESS               The method is successful.
 383          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 384          *                                                                      The specified @c item is not constructed.
 385          * @exception   E_OUT_OF_RANGE          The specified @c index is out of the range of the data structure. @n
 386          *                                                                      The specified @c index is either greater than or equal to the number of items or is less than @c 0.
 387          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 388          * @exception   E_SYSTEM                        A system error has occurred.
 389          * @remarks     The contents of the specified item are copied. @n
 390          *              The item can be deallocated explicitly after this method call if it is created dynamically.
 391          */
 392         result SetItemAt(int index, const TabBarItem& item);
 393
 394
 395         /**
 396          * Selects the item at the specified index.
 397          *
 398          * @since       2.0
 399          *
 400          * @return      An error code
 401          * @param[in]   index                   The index of the item to select
 402          * @exception   E_SUCCESS               The method is successful.
 403          * @exception   E_OUT_OF_RANGE          The specified @c index is not within the range of the data structure. @n
 404          *                                                                      The specified @c index is either greater than or equal to the number of items or is less than @c 0.
 405          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 406          * @exception   E_SYSTEM                A system error has occurred.
 407          */
 408         result SetItemSelected(int index);
 409
 410
 411         /**
 412          * Sets the item text color for the specified state.
 413          *
 414          * @since       2.0
 415          *
 416          * @return      An error code
 417          * @param[in]   status            The item state
 418          * @param[in]   color             The item text color
 419          * @exception   E_SUCCESS         The method is successful.
 420          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 421          * @exception   E_SYSTEM          A system error has occurred.
 422          */
 423         result SetItemTextColor(TabBarItemStatus status, const Tizen::Graphics::Color& color);
 424
 425
 426         /**
 427          * Sets the selected item color.
 428          *
 429          * @since       2.0
 430          *
 431          * @return      An error code
 432          * @param[in]   color             The item color
 433          * @exception   E_SUCCESS         The method is successful.
 434          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 435          * @exception   E_SYSTEM          A system error has occurred.
 436          */
 437         result SetSelectedItemColor(const Tizen::Graphics::Color& color);
 438
 439
 440         /**
 441          * Sets the width of the tab bar.
 442          *
 443          * @since       2.0
 444          *
 445          * @return      An error code
 446          * @param[in]   width             The width
 447          * @exception   E_SUCCESS         The method is successful.
 448          * @exception   E_INVALID_ARG     The specified input parameter is invalid.
 449          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 450          * @exception   E_SYSTEM          A system error has occurred.
 451          */
 452         result SetWidth(int width);
 453
 454         /**
 455          * Sets the width of the tab bar.
 456          *
 457          * @since       2.1
 458          *
 459          * @return      An error code
 460          * @param[in]   width             The width
 461          * @exception   E_SUCCESS         The method is successful.
 462          * @exception   E_INVALID_ARG     The specified input parameter is invalid.
 463          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 464          * @exception   E_SYSTEM          A system error has occurred.
 465          */
 466         result SetWidth(float width);
 467
 468
 469 //Listeners
 470 public:
 471         /**
 472          * Adds an action event listener instance. @n
 473          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 474          *
 475          * @since               2.0
 476          *
 477          * @param[in]   listener                The event listener to add
 478          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 479          */
 480         void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
 481
 482
 483         /**
 484          * Removes an action event listener instance. @n
 485          * The removed listener cannot listen to events when they are fired.
 486          *
 487          * @since               2.0
 488          *
 489          * @param[in]   listener                The event listener to remove
 490          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 491          */
 492         void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
 493
 494 protected:
 495         friend class _TabBarImpl;
 496
 497 private:
 498         //
 499         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 500         //
 501         // @since       2.0
 502         //
 503         //
 504         TabBar(const TabBar& rhs);
 505
 506         //
 507         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 508         //
 509         // @since       2.0
 510         //
 511         //
 512         TabBar& operator =(const TabBar& rhs);
 513
 514 }; // TabBar
 515
 516 }}} // Tizen::Ui: Control
 517 #endif //_FUI_CTRL_TAB_BAR_H_