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