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