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 // Operation
 198 public:
 199         /**
 200          * Adds the specified item.
 201          *
 202          * @since       2.0
 203          *
 204          * @return      An error code
 205          * @param[in]   item                    The item to be added
 206          * @exception   E_SUCCESS               The method is successful.
 207          * @exception   E_INVALID_ARG           The specified input parameter is invalid. @n
 208          *                                                                      The specified @c item is not constructed.
 209          * @exception   E_MAX_EXCEEDED          The number of items has exceeded the maximum limit.
 210          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 211          * @exception   E_SYSTEM                A system error has occurred.
 212          * @remarks             The maximum number of items for a %TabBar control is @c 100. @n
 213          *              However, the content of the specified item is copied to the %TabBar control. @n
 214          *              The item can be deallocated explicitly after this method call if it is created dynamically. @n
 215          *              The %TabBar control does not throw any exception even though the same action ID is assigned to multiple items.
 216          */
 217         result AddItem(const TabBarItem& item);
 218
 219
 220         /**
 221          * Inserts the %TabBar item at the specified index.
 222          *
 223          * @since       2.0
 224          *
 225          * @return      An error code
 226          * @param[in]   index                   The index of the item to be inserted
 227          * @param[in]   item                    The item to be inserted
 228          * @exception   E_SUCCESS               The method is successful.
 229          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 230          *                                                                      The specified @c item is not constructed.
 231          * @exception   E_MAX_EXCEEDED          The number of items has exceeded the maximum limit.
 232          * @exception   E_OUT_OF_RANGE          The specified @c index is out of the range of the data structure. @n
 233          *                                                                      The specified @c index is either greater than or equal to the number of items or is less than @c 0.
 234          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 235          * @exception   E_SYSTEM                A system error has occurred.
 236          * @remarks     The maximum number of items for a %TabBar control is @c 100. @n
 237          *              However, the content of the specified item is copied to the @c %TabBar control. @n
 238          *              The item can be deallocated explicitly after this method call if it is created dynamically. @n
 239          *              The %TabBar control does not throw any exception even though the same action ID is assigned to multiple items.
 240          */
 241         result InsertItemAt(int index, const TabBarItem& item);
 242
 243
 244         /**
 245          * Gets the color of the %TabBar control.
 246          *
 247          * @since       2.0
 248          *
 249          * @return      The color, @n
 250          *                              else RGBA(0,0,0,0) if an error occurs
 251          * @exception   E_SUCCESS           The method is successful.
 252          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 253          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 254          */
 255         Tizen::Graphics::Color GetColor(void) const;
 256
 257
 258         /**
 259          * Gets the item count.
 260          *
 261          * @since       2.0
 262          *
 263          * @return      The item count, @n
 264          *              else @c -1 if an error occurs
 265          * @exception   E_SUCCESS           The method is successful.
 266          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 267          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 268          */
 269         int GetItemCount(void) const;
 270
 271
 272         /**
 273          * Gets the item color that is displayed when an item is selected.
 274          *
 275          * @since       2.0
 276          *
 277          * @return      The selected item color, @n
 278          *                              else RGBA(0,0,0,0) if an error occurs
 279          * @exception   E_SUCCESS           The method is successful.
 280          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 281          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 282          */
 283         Tizen::Graphics::Color GetSelectedItemColor(void) const;
 284
 285
 286         /**
 287          * Gets the item text color for the specified state.
 288          *
 289          * @since       2.0
 290          *
 291          * @return      The item text color, @n
 292          *                              else RGBA (0,0,0,0) if an error occurs
 293          * @param[in]   status              The item state
 294          * @exception   E_SUCCESS           The method is successful.
 295          * @exception   E_INVALID_STATE     This instance is in an invalid state.
 296          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 297          */
 298         Tizen::Graphics::Color GetItemTextColor(TabBarItemStatus status) const;
 299
 300
 301         /**
 302          * Gets the index of the selected item.
 303          *
 304          * @since       2.0
 305          *
 306          * @return      The selected item index, @n
 307          *              else @c -1 if an error occurs
 308          * @exception   E_SUCCESS               The method is successful.
 309          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 310          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 311          */
 312         int GetSelectedItemIndex(void) const;
 313
 314
 315         /**
 316          * Removes the %TabBar item at the specified index.
 317          *
 318          * @since       2.0
 319          *
 320          * @return      An error code
 321          * @param[in]   index                   The index of the item
 322          * @exception   E_SUCCESS               The method is successful.
 323          * @exception   E_OUT_OF_RANGE          The specified @c index is out of the range of the data structure. @n
 324          *                                                                      The specified @c index is either greater than or equal to the number of items or is less than @c 0.
 325          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 326          * @exception   E_SYSTEM                A system error has occurred.
 327          * @remarks     If the currently selected item is removed, the next item is selected automatically.
 328          */
 329         result RemoveItemAt(int index);
 330
 331
 332         /**
 333          * Removes all the items from the %TabBar control.
 334          *
 335          * @since       2.0
 336          *
 337          * @return      An error code
 338          * @exception   E_SUCCESS         The method is successful.
 339          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 340          * @exception   E_SYSTEM          A system error has occurred.
 341          */
 342         result RemoveAllItems(void);
 343
 344
 345         /**
 346          * Sets the color of the %TabBar control.
 347          *
 348          * @since       2.0
 349          *
 350          * @return      An error code
 351          * @param[in]   color             The color
 352          * @exception   E_SUCCESS         The method is successful.
 353          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 354          */
 355         result SetColor(const Tizen::Graphics::Color& color);
 356
 357
 358         /**
 359          * Sets the content of the %TabBar item at the specified index.
 360          *
 361          * @since       2.0
 362          *
 363          * @return      An error code
 364          * @param[in]   index                   The index at which to set the specified item
 365          * @param[in]   item                    The item to be set
 366          * @exception   E_SUCCESS               The method is successful.
 367          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 368          *                                                                      The specified @c item is not constructed.
 369          * @exception   E_OUT_OF_RANGE          The specified @c index is out of the range of the data structure. @n
 370          *                                                                      The specified @c index is either greater than or equal to the number of items or is less than @c 0.
 371          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 372          * @exception   E_SYSTEM                        A system error has occurred.
 373          * @remarks     The contents of the specified item are copied. @n
 374          *              The item can be deallocated explicitly after this method call if it is created dynamically.
 375          */
 376         result SetItemAt(int index, const TabBarItem& item);
 377
 378
 379         /**
 380          * Selects the item at the specified index.
 381          *
 382          * @since       2.0
 383          *
 384          * @return      An error code
 385          * @param[in]   index                   The index of the item to be selected
 386          * @exception   E_SUCCESS               The method is successful.
 387          * @exception   E_OUT_OF_RANGE          The specified @c index is not within the range of the data structure. @n
 388          *                                                                      The specified @c index is either greater than or equal to the number of items or is less than @c 0.
 389          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 390          * @exception   E_SYSTEM                A system error has occurred.
 391          */
 392         result SetItemSelected(int index);
 393
 394
 395         /**
 396          * Sets the item text color for the specified state.
 397          *
 398          * @since       2.0
 399          *
 400          * @return      An error code
 401          * @param[in]   status            The item state
 402          * @param[in]   color             The item text color
 403          * @exception   E_SUCCESS         The method is successful.
 404          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 405          * @exception   E_SYSTEM          A system error has occurred.
 406          */
 407         result SetItemTextColor(TabBarItemStatus status, const Tizen::Graphics::Color& color);
 408
 409
 410         /**
 411          * Sets the selected item color.
 412          *
 413          * @since       2.0
 414          *
 415          * @return      An error code
 416          * @param[in]   color             The item color
 417          * @exception   E_SUCCESS         The method is successful.
 418          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 419          * @exception   E_SYSTEM          A system error has occurred.
 420          */
 421         result SetSelectedItemColor(const Tizen::Graphics::Color& color);
 422
 423
 424         /**
 425          * Sets the width of the tab bar.
 426          *
 427          * @since       2.0
 428          *
 429          * @return      An error code
 430          * @param[in]   width             The width
 431          * @exception   E_SUCCESS         The method is successful.
 432          * @exception   E_INVALID_ARG     The specified input parameter is invalid.
 433          * @exception   E_INVALID_STATE   This instance is in an invalid state.
 434          * @exception   E_SYSTEM          A system error has occurred.
 435          */
 436         result SetWidth(int width);
 437
 438
 439 //Listeners
 440 public:
 441         /**
 442          * Adds an action event listener instance. @n
 443          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 444          *
 445          * @since               2.0
 446          *
 447          * @param[in]   listener                The event listener to be added
 448          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 449          */
 450         void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
 451
 452
 453         /**
 454          * Removes an action event listener instance. @n
 455          * The removed listener cannot listen to events when they are fired.
 456          *
 457          * @since               2.0
 458          *
 459          * @param[in]   listener                The event listener to be removed
 460          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 461          */
 462         void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
 463
 464 protected:
 465         friend class _TabBarImpl;
 466
 467 private:
 468         //
 469         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 470         //
 471         // @since       2.0
 472         //
 473         //
 474         TabBar(const TabBar& rhs);
 475
 476         //
 477         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 478         //
 479         // @since       2.0
 480         //
 481         //
 482         TabBar& operator =(const TabBar& rhs);
 483
 484 }; // TabBar
 485
 486 }}} // Tizen::Ui: Control
 487 #endif //_FUI_CTRL_TAB_BAR_H_