inc/FUiCtrlGroupedTableView.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 FUiCtrlGroupedTableView.h
  20 * @brief This is the header file for the %GroupedTableView class.
  21 *
  22 * This header file contains the declarations of the %GroupedTableView class and its helper classes.
  23 */
  24
  25 #ifndef _FUI_CTRL_GROUPED_TABLE_VIEW_H_
  26 #define _FUI_CTRL_GROUPED_TABLE_VIEW_H_
  27
  28 #include <FGrpRectangle.h>
  29 #include <FGrpColor.h>
  30 #include <FUiContainer.h>
  31 #include <FUiCtrlTableViewTypes.h>
  32 #include <FUiCtrlScrollPanelTypes.h>
  33
  34 namespace Tizen { namespace Ui { namespace Controls
  35 {
  36 class IGroupedTableViewItemProvider;
  37 class IGroupedTableViewItemProviderF;
  38 class IGroupedTableViewItemEventListener;
  39 class IFastScrollListener;
  40 class IScrollEventListener;
  41 class IScrollEventListenerF;
  42
  43 /**
  44  * @class GroupedTableView
  45  * @brief   This class defines common behavior for a %GroupedTableView control.
  46  *
  47  * @since 2.0
  48  *
  49  * The %GroupedTableView class defines common behavior for a %GroupedTableView control.
  50  *
  51  * The following example demonstrates how to use the %GroupedTableView class.
  52  *
  53  * @code
  54 //Sample code for GroupedTableViewSample.h
  55 #include <FUi.h>
  56
  57 class GroupedTableViewSample
  58         : public Tizen::Ui::Controls::Form
  59         , public Tizen::Ui::Controls::IGroupedTableViewItemProvider
  60         , public Tizen::Ui::Controls::IGroupedTableViewItemEventListener
  61         , public Tizen::Ui::Controls::IFastScrollListener
  62 {
  63 public:
  64         GroupedTableViewSample(void)
  65         : __pGroupedTableView(null)
  66         , __pContextItem(null){}
  67
  68         bool Initialize(void);
  69         virtual result OnInitializing(void);
  70         virtual result OnTerminating(void);
  71
  72         // IGroupedTableViewItemEventListener
  73         virtual void OnGroupedTableViewGroupItemStateChanged(Tizen::Ui::Controls::GroupedTableView& tableView, int groupIndex, Tizen::Ui::Controls::TableViewGroupItem* pItem, Tizen::Ui::Controls::TableViewItemStatus status);
  74         virtual void OnGroupedTableViewItemStateChanged(Tizen::Ui::Controls::GroupedTableView& tableView, int groupIndex, int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem, Tizen::Ui::Controls::TableViewItemStatus status);
  75         virtual void OnGroupedTableViewContextItemActivationStateChanged(Tizen::Ui::Controls::GroupedTableView& tableView, int groupIndex, int itemIndex, Tizen::Ui::Controls::TableViewContextItem* pContextItem, bool activated);
  76
  77         // IGroupedTableViewItemProvider
  78         virtual int GetGroupCount(void);
  79         virtual int GetItemCount(int groupIndex);
  80         virtual Tizen::Ui::Controls::TableViewGroupItem* CreateGroupItem(int groupIndex, int itemWidth);
  81         virtual bool DeleteGroupItem(int groupIndex, Tizen::Ui::Controls::TableViewGroupItem* pItem);
  82         virtual void UpdateGroupItem(int groupIndex, Tizen::Ui::Controls::TableViewGroupItem* pItem);
  83         virtual Tizen::Ui::Controls::TableViewItem* CreateItem(int groupIndex, int itemIndex, int itemWidth);
  84         virtual bool DeleteItem(int groupIndex, int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem);
  85         virtual void UpdateItem(int groupIndex, int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem);
  86         virtual int GetDefaultItemHeight(void);
  87         virtual int GetDefaultGroupItemHeight(void);
  88
  89         // IFastScrollListener
  90         virtual void OnFastScrollIndexSelected(Tizen::Ui::Control& source, Tizen::Base::String& index);
  91
  92 private:
  93         Tizen::Ui::Controls::GroupedTableView* __pGroupedTableView;
  94         Tizen::Ui::Controls::TableViewContextItem* __pContextItem;
  95 };
  96  *  @endcode
  97  *
  98  *  @code
  99
 100 //Sample code for GroupedTableViewSample.cpp
 101 #include <FApp.h>
 102 #include <FGraphics.h>
 103
 104 #include "GroupedTableViewSample.h"
 105
 106 using namespace Tizen::App;
 107 using namespace Tizen::Base;
 108 using namespace Tizen::Graphics;
 109 using namespace Tizen::Media;
 110 using namespace Tizen::Ui::Controls;
 111
 112 bool
 113 GroupedTableViewSample::Initialize(void)
 114 {
 115         Construct(FORM_STYLE_NORMAL);
 116         return true;
 117 }
 118
 119 result
 120 GroupedTableViewSample::OnInitializing(void)
 121 {
 122         result r = E_SUCCESS;
 123
 124         // Creates an instance of TableView
 125         __pGroupedTableView = new GroupedTableView();
 126         __pGroupedTableView->Construct(Rectangle(0, 0, GetClientAreaBounds().width, GetClientAreaBounds().height), true, TABLE_VIEW_SCROLL_BAR_STYLE_FAST_SCROLL);
 127         __pGroupedTableView->SetItemProvider(this);
 128         __pGroupedTableView->AddGroupedTableViewItemEventListener(*this);
 129
 130         __pGroupedTableView->AddFastScrollListener(*this);
 131         __pGroupedTableView->SetFastScrollIndex(L"ABCDEFGHIJKLMNOPQRSTUVWXYZ", true);
 132
 133         // Adds the TableView to the form
 134         AddControl(__pGroupedTableView);
 135
 136         // Creates an instance of TableViewContextItem
 137         __pContextItem = new TableViewContextItem();
 138         __pContextItem->Construct(Dimension(720, 100));
 139
 140         Button* pButton = new Button();
 141         pButton->Construct(Rectangle(10, 10, 200, 80), L"Context1");
 142
 143         Button* pButton2 = new Button();
 144         pButton2->Construct(Rectangle(250, 10, 200, 80), L"Context2");
 145
 146         __pContextItem->AddControl(pButton);
 147         __pContextItem->AddControl(pButton2);
 148
 149         return r;
 150 }
 151
 152 result
 153 GroupedTableViewSample::OnTerminating(void)
 154 {
 155         result r = E_SUCCESS;
 156
 157         // Deallocates the item context
 158         delete __pContextItem;
 159         __pContextItem = null;
 160
 161         return r;
 162 }
 163
 164 // IGroupedTableViewItemEventListener implementation
 165 void
 166 GroupedTableViewSample::OnGroupedTableViewGroupItemStateChanged(GroupedTableView& tableView, int groupIndex, TableViewGroupItem* pItem, TableViewItemStatus status)
 167 {
 168         if (tableView.IsGroupExpanded(groupIndex))
 169         {
 170                 tableView.CollapseGroup(groupIndex);
 171         }
 172         else
 173         {
 174                 tableView.ExpandGroup(groupIndex);
 175         }
 176 }
 177
 178 void
 179 GroupedTableViewSample::OnGroupedTableViewItemStateChanged(GroupedTableView& tableView, int groupIndex, int itemIndex, TableViewItem* pItem, TableViewItemStatus status)
 180 {
 181         // ....
 182 }
 183
 184 void
 185 GroupedTableViewSample::OnGroupedTableViewContextItemActivationStateChanged(GroupedTableView& tableView, int groupIndex, int itemIndex, TableViewContextItem* pContextItem, bool activated)
 186 {
 187         // ....
 188 }
 189
 190 // IFastScrollListener implementation
 191 void
 192 GroupedTableViewSample::OnFastScrollIndexSelected(Tizen::Ui::Control& source, Tizen::Base::String& index)
 193 {
 194         // ....
 195 }
 196
 197 // IGroupedTableViewItemProvider implementation
 198 int
 199 GroupedTableViewSample::GetGroupCount(void)
 200 {
 201         return 26;
 202 }
 203
 204 int
 205 GroupedTableViewSample::GetItemCount(int groupIndex)
 206 {
 207         return 10;
 208 }
 209
 210 int
 211 GroupedTableViewSample::GetDefaultItemHeight(void)
 212 {
 213         return 100;
 214 }
 215
 216 int
 217 GroupedTableViewSample::GetDefaultGroupItemHeight(void)
 218 {
 219         return 80;
 220 }
 221
 222 TableViewGroupItem*
 223 GroupedTableViewSample::CreateGroupItem(int groupIndex, int itemWidth)
 224 {
 225         TableViewGroupItem* pItem = new TableViewGroupItem();
 226         pItem->Construct(Dimension(itemWidth, GetDefaultGroupItemHeight()));
 227
 228         String text;
 229         text.Format(30, L"Group title %d", groupIndex);
 230
 231         Label* pLabel = new Label();
 232         pLabel->Construct(Rectangle(0, 0, itemWidth, GetDefaultGroupItemHeight()), text);
 233
 234         pItem->AddControl(pLabel);
 235
 236         return pItem;
 237 }
 238
 239 bool
 240 GroupedTableViewSample::DeleteGroupItem(int groupIndex, TableViewGroupItem* pItem)
 241 {
 242         pItem->Destroy();
 243
 244         return true;
 245 }
 246
 247 void
 248 GroupedTableViewSample::UpdateGroupItem(int groupIndex, TableViewGroupItem* pItem)
 249 {
 250         // ....
 251 }
 252
 253 TableViewItem*
 254 GroupedTableViewSample::CreateItem(int groupIndex, int itemIndex, int itemWidth)
 255 {
 256         TableViewAnnexStyle style = TABLE_VIEW_ANNEX_STYLE_NORMAL;
 257         TableViewItem* pItem = new TableViewItem();
 258
 259         switch (itemIndex % 6)
 260         {
 261         case 0:
 262                 style = TABLE_VIEW_ANNEX_STYLE_NORMAL;
 263                 break;
 264         case 1:
 265                 style = TABLE_VIEW_ANNEX_STYLE_MARK;
 266                 break;
 267         case 2:
 268                 style = TABLE_VIEW_ANNEX_STYLE_ONOFF_SLIDING;
 269                 break;
 270         case 3:
 271                 style = TABLE_VIEW_ANNEX_STYLE_DETAILED;
 272                 break;
 273         case 4:
 274                 style = TABLE_VIEW_ANNEX_STYLE_RADIO;
 275                 break;
 276         case 5:
 277                 style = TABLE_VIEW_ANNEX_STYLE_ONOFF_SLIDING_WITH_DIVIDER;
 278                 break;
 279         default:
 280                 break;
 281         }
 282
 283         pItem->Construct(Dimension(itemWidth, GetDefaultItemHeight()), style);
 284
 285         String text;
 286         text.Format(30, L"TableViewItem %d", itemIndex);
 287
 288         Label* pLabel = new Label();
 289         pLabel->Construct(Rectangle(0, 0, itemWidth, GetDefaultItemHeight()), text);
 290
 291         pItem->AddControl(pLabel);
 292         pItem->SetContextItem(__pContextItem);
 293
 294         return pItem;
 295 }
 296
 297 bool
 298 GroupedTableViewSample::DeleteItem(int groupIndex, int itemIndex, TableViewItem* pItem)
 299 {
 300         pItem->Destroy();
 301
 302         return true;
 303 }
 304
 305 void
 306 GroupedTableViewSample::UpdateItem(int groupIndex, int itemIndex, TableViewItem* pItem)
 307 {
 308         // ....
 309 }
 310  * @endcode
 311  *
 312  */
 313
 314 class _OSP_EXPORT_ GroupedTableView
 315         : public Tizen::Ui::Container
 316 {
 317 public:
 318         /**
 319         * The object is not fully constructed after this constructor is called. @n
 320         * For full construction, the %Construct() method must be called right after calling this constructor.
 321         *
 322         * @since 2.0
 323         */
 324         GroupedTableView(void);
 325
 326         /**
 327         * This destructor overrides Tizen::Base::Object::~Object().
 328         *
 329         * @since 2.0
 330         */
 331         virtual ~GroupedTableView(void);
 332
 333         /**
 334         * Initializes this instance of %GroupedTableView with the specified parameters.
 335         *
 336         * @since 2.0
 337         *
 338         * @return  An error code
 339         * @param[in] rect    An instance of the Graphics::Rectangle class @n
 340         *                              This instance represents the x and y coordinates of the left top corner of the created %GroupedTableView along with
 341         *                                       the width and height.@n
 342         *                                                               The optimal size of the control is defined in
 343         *                                                               <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 344         * @param[in] itemDivider       Set to @c true to display an item divider, @n
 345         *                              else @c false
 346         * @param[in] scrollStyle       The style of %GroupedTableView scroll bar style
 347         * @exception E_SUCCESS         The method is successful.
 348         * @exception E_INVALID_ARG     A specified input parameter is invalid, or either the rect.width or rect.height parameter has a negative value.
 349         *
 350         */
 351         result Construct(const Tizen::Graphics::Rectangle& rect, bool itemDivider, TableViewScrollBarStyle scrollStyle);
 352
 353         /**
 354         * Initializes this instance of %GroupedTableView with the specified parameters.
 355         *
 356         * @since 2.1
 357         *
 358         * @return  An error code
 359         * @param[in] rect    An instance of the Tizen::Graphics::FloatRectangle class @n
 360         *                              This instance represents the x and y coordinates of the left top corner of the created %GroupedTableView along with
 361         *                                       the width and height.@n
 362         *                                                               The optimal size of the control is defined in
 363         *                                                               <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 364         * @param[in] itemDivider       Set to @c true to display an item divider, @n
 365         *                              else @c false
 366         * @param[in] scrollStyle       The style of %GroupedTableView scroll bar style
 367         * @exception E_SUCCESS         The method is successful.
 368         * @exception E_INVALID_ARG     A specified input parameter is invalid, or either the rect.width or rect.height parameter has a negative value.
 369         *
 370         */
 371         result Construct(const Tizen::Graphics::FloatRectangle& rect, bool itemDivider, TableViewScrollBarStyle scrollStyle);
 372
 373         /**
 374         * Sets the item provider that creates and deletes items for the grouped style table view.
 375         *
 376         * @since 2.0
 377         *
 378         * @param[in] pProvider                                 The item provider to create and delete items
 379         * @remarks
 380         *                       - If an item provider is not set for the table view, the table view does not work.
 381         *                       - The specified provider should be allocated in heap memory.
 382         *                       - To reset the item provider, pass @c null to @c pProvider.
 383         */
 384         void SetItemProvider(IGroupedTableViewItemProvider* pProvider);
 385
 386         /**
 387         * Sets the item provider that creates and deletes items for the grouped style table view.
 388         *
 389         * @since 2.1
 390         *
 391         * @param[in] pProvider                                 The item provider to create and delete items
 392         * @remarks
 393         *                       - If an item provider is not set for the table view, the table view does not work.
 394         *                       - The specified provider should be allocated in heap memory.
 395         *                       - To reset the item provider, pass @c null to @c pProvider.
 396         */
 397         void SetItemProviderF(IGroupedTableViewItemProviderF* pProvider);
 398
 399         /**
 400         * Expands the group's items.
 401         *
 402         * @since 2.0
 403         *
 404         * @return An error code
 405         * @param[in] groupIndex The index of the group
 406         * @exception E_SUCCESS             The method is successful.
 407         * @exception E_OUT_OF_RANGE        A specified input parameter is invalid.
 408         * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation @b Since: @b 2.1.
 409         * @remarks
 410         *                       - This method does not work during the ITableViewItemProvider call-back procedure.
 411         *                       - This method should be called only after TableView items are created. If this method needs to be called early in the lifecycle of the
 412         *                       TableView, then UpdateTableView() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 413         */
 414         result ExpandGroup(int groupIndex);
 415
 416         /**
 417         * Collapses the group's items.
 418         *
 419         * @since 2.0
 420         *
 421         * @return An error code
 422         * @param[in] groupIndex The index of the group
 423         * @exception E_SUCCESS         The method is successful.
 424         * @exception E_OUT_OF_RANGE           A specified input parameter is invalid.
 425         * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation @b Since: @b 2.1.
 426         * @remarks
 427         *                       - This method does not work during the ITableViewItemProvider call-back procedure.
 428         *                       - This method should be called only after TableView items are created. If this method needs to be called early in the lifecycle of the
 429         *                       TableView, then UpdateTableView() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 430         */
 431         result CollapseGroup(int groupIndex);
 432
 433         /**
 434         * Expands all groups of table view.
 435         *
 436         * @since 2.0
 437         *
 438         * @return An error code
 439         * @exception E_SUCCESS             The method is successful.
 440         * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation @b Since: @b 2.1.
 441         * @remarks This method does not work during the ITableViewItemProvider call-back procedure.
 442         */
 443         result ExpandAllGroups(void);
 444
 445         /**
 446         * Collapses all groups of table view.
 447         *
 448         * @since 2.0
 449         *
 450         * @return An error code
 451         * @exception E_SUCCESS             The method is successful.
 452         * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation @b Since: @b 2.1.
 453         * @remarks This method does not work during the ITableViewItemProvider call-back procedure.
 454         */
 455         result CollapseAllGroups(void);
 456
 457         /*
 458         * Expands all groups of table view.
 459         *
 460         * @since 2.0
 461         *
 462         */
 463         inline void ExpandAllGroup(void)
 464         {
 465                 ExpandAllGroups();
 466         }
 467
 468         /*
 469         * Collapses all groups of table view.
 470         *
 471         * @since 2.0
 472         *
 473         */
 474         inline void CollapseAllGroup(void)
 475         {
 476                 CollapseAllGroups();
 477         }
 478
 479         /**
 480         * Returns whether the group is expanded or not.
 481         *
 482         * @since 2.0
 483         *
 484         * @return @c true if the group is expanded, @n
 485         *               else @c false
 486         * @param[in] groupIndex The index of the group
 487         * @exception E_SUCCESS  The method is successful.
 488         * @exception E_OUT_OF_RANGE           A specified input parameter is invalid.
 489         * @remarks This method should be called only after TableView items are created. If this method needs to be called early in the lifecycle of the
 490         *                       TableView, then UpdateTableView() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 491         */
 492         bool IsGroupExpanded(int groupIndex) const;
 493
 494         /**
 495         * Sets the grouped look is enabled.
 496         *
 497         * @since 2.0
 498         *
 499         * @param[in] enable   The enabled/disabled status
 500         */
 501         void SetGroupedLookEnabled(bool enable);
 502
 503         /**
 504         * Returns whether the grouped look is enabled or not.
 505         *
 506         * @since 2.0
 507         *
 508         * @return @c true if the grouped look is enabled, @n
 509         *               else @c false
 510         */
 511         bool IsGroupedLookEnabled(void) const;
 512
 513         /**
 514         * Adds a listener instance that listens to state changes of table view items. @n
 515         * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 516         *
 517         * @since 2.0
 518         *
 519         * @return  An error code
 520         * @param[in] listener      The event listener to add
 521         * @exception E_SUCCESS                                          The method is successful.
 522         * @exception E_OBJ_ALREADY_EXIST      The listener is already added.
 523         * @remarks   The specified listener should be allocated in heap memory.
 524         */
 525         result AddGroupedTableViewItemEventListener(IGroupedTableViewItemEventListener& listener);
 526
 527         /**
 528         * Removes a listener instance that listens to state changes of table view items. @n
 529         * The removed listener cannot listen to events when they are fired.
 530         *
 531         * @since 2.0
 532         *
 533         * @return  An error code
 534         * @param[in] listener   The event listener to remove
 535         * @exception   E_SUCCESS                             The method is successful.
 536         * @exception   E_OBJ_NOT_FOUND                  The listener is not found.
 537         */
 538         result RemoveGroupedTableViewItemEventListener(IGroupedTableViewItemEventListener& listener);
 539
 540         /**
 541         * Adds a listener instance that listens to state changes of a fast scroll. @n
 542         * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 543         *
 544         * @since 2.0
 545         *
 546         * @return  An error code
 547         * @param[in] listener   The event listener to add
 548         * @exception   E_SUCCESS                             The method is successful.
 549         * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 550         * @exception   E_OBJ_ALREADY_EXIST   The listener is already added.
 551         * @remarks   The specified listener should be allocated in heap memory.
 552         */
 553         result AddFastScrollListener(IFastScrollListener& listener);
 554
 555         /**
 556         * Removes a listener instance that listens to state changes of a fast scroll. @n
 557         * The removed listener cannot listen to events when they are fired.
 558         *
 559         * @since 2.0
 560         *
 561         * @return  An error code
 562         * @param[in] listener   The event listener to remove
 563         * @exception   E_SUCCESS                             The method is successful.
 564         * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 565         * @exception   E_OBJ_NOT_FOUND                  The listener is not found.
 566         */
 567         result RemoveFastScrollListener(IFastScrollListener& listener);
 568
 569         /**
 570         * Adds a listener instance that listens to state changes of a scroll event. @n
 571         * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 572         *
 573         * @since 2.0
 574         *
 575         * @return  An error code
 576         * @param[in] listener          The event listener to add
 577         * @exception   E_SUCCESS                             The method is successful.
 578         * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 579         * @exception   E_OBJ_ALREADY_EXIST   The listener is already added.
 580         * @remarks   The specified listener should be allocated in heap memory.
 581         * @see     IScrollEventListener::OnScrollEndReached()
 582         * @see     RemoveScrollEventListener()
 583         */
 584         result AddScrollEventListener(IScrollEventListener& listener);
 585
 586         /**
 587         * Removes a listener instance that listens to state changes of a scroll event. @n
 588         * The removed listener cannot listen to events when they are fired.
 589         *
 590         * @since 2.0
 591         *
 592         * @return  An error code
 593         * @param[in] listener   The event listener to remove
 594         * @exception   E_SUCCESS                             The method is successful.
 595         * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 596         * @exception   E_OBJ_NOT_FOUND                  The listener is not found.
 597         * @see  IScrollEventListener::OnScrollEndReached()
 598         * @see     AddScrollEventListener()
 599         */
 600         result RemoveScrollEventListener(IScrollEventListener& listener);
 601
 602         /**
 603         * Adds a listener instance that listens to state changes of a scroll event. @n
 604         * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 605         *
 606         * @since 2.1
 607         *
 608         * @return  An error code
 609         * @param[in] listener          The event listener to add
 610         * @exception   E_SUCCESS                             The method is successful.
 611         * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 612         * @exception   E_OBJ_ALREADY_EXIST   The listener is already added.
 613         * @remarks   The specified listener should be allocated in heap memory.
 614         * @see     IScrollEventListenerF::OnScrollEndReached()
 615         * @see     RemoveScrollEventListenerF()
 616         */
 617         result AddScrollEventListener(IScrollEventListenerF& listener);
 618
 619         /**
 620         * Removes a listener instance that listens to state changes of a scroll event. @n
 621         * The removed listener cannot listen to events when they are fired.
 622         *
 623         * @since 2.1
 624         *
 625         * @return  An error code
 626         * @param[in] listener   The event listener to remove
 627         * @exception   E_SUCCESS                             The method is successful.
 628         * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 629         * @exception   E_OBJ_NOT_FOUND                  The listener is not found.
 630         * @see  IScrollEventListenerF::OnScrollEndReached()
 631         * @see     AddScrollEventListenerF()
 632         */
 633         result RemoveScrollEventListener(IScrollEventListenerF& listener);
 634
 635         /**
 636         * Enables or disables the collapse by pinch gesture.
 637         *
 638         * @since 2.0
 639         *
 640         * @param[in] enable   Set to @c true to enable the collapse by pinch gesture, else @c false
 641         */
 642         void SetCollapseByPinchGestureEnabled(bool enable);
 643
 644         /**
 645         * Returns whether the collapse by pinch gesture is enabled or not.
 646         *
 647         * @since 2.0
 648         *
 649         * @return @c true if the collapse by pinch gesture is enabled, @n
 650         *               else @c false
 651         */
 652         bool IsCollapseByPinchGestureEnabled(void) const;
 653
 654         /**
 655         * Sets the text index of the fast scroll.
 656         *
 657         * @since 2.0
 658         *
 659         * @return  An error code
 660         * @param[in] text                    The text of the index
 661         * @param[in] useSearchIcon           Set to @c true to show the magnifying icon, @n
 662         *                                    else @c false
 663         * @exception E_SUCCESS               The method is successful.
 664         * @exception E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
 665         */
 666         result SetFastScrollIndex(const Tizen::Base::String& text, bool useSearchIcon);
 667
 668         /**
 669         * Gets the group and item indexes of the top item.
 670         *
 671         * @since 2.0
 672         *
 673         * @return        An error code
 674         * @param[out]  groupIndex                 The group index
 675         * @param[out]  itemIndex                  The item index
 676         * @exception   E_SUCCESS                  The method is successful.
 677         * @exception   E_OBJ_NOT_FOUND            Top drawn item is not found.
 678         */
 679         result GetTopDrawnItemIndex(int& groupIndex, int& itemIndex) const;
 680
 681         /**
 682         * Gets the group and item indexes of the bottom item.
 683         *
 684         * @since 2.0
 685         *
 686         * @return        An error code
 687         * @param[out]  groupIndex                 The group index
 688         * @param[out]  itemIndex                  The item index
 689         * @exception   E_SUCCESS                  The method is successful.
 690         * @exception   E_OBJ_NOT_FOUND            Bottom drawn item is not found.
 691         */
 692         result GetBottomDrawnItemIndex(int& groupIndex, int& itemIndex) const;
 693
 694         /**
 695         * Scrolls to the item at the specified index.
 696         * The specified item is drawn at the position specified by the item alignment.
 697         *
 698         * @since 2.0
 699         *
 700         * @return  An error code
 701         * @param[in] groupIndex            The group index
 702         * @param[in] itemIndex             The item index
 703         * @param[in] itemAlignment         The item alignment
 704         * @exception E_SUCCESS             The method is successful.
 705         * @exception E_OUT_OF_RANGE        A specified input parameter is invalid.
 706         * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation @b Since: @b 2.1.
 707         * @remarks
 708         *                       - If the specified item. itemIndex is @c -1, then the method is applied to the group item with the given index.
 709         *                         This method does not work during the ITableViewItemProvider call-back procedure.
 710         *                       - This method should be called only after TableView items are created. If this method needs to be called early in the lifecycle of the
 711         *                       TableView, then UpdateTableView() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 712         */
 713         result ScrollToItem(int groupIndex, int itemIndex, TableViewScrollItemAlignment itemAlignment = TABLE_VIEW_SCROLL_ITEM_ALIGNMENT_TOP);
 714
 715         /**
 716         * Checks or unchecks the item at the specified index.
 717         *
 718         * @since 2.0
 719         *
 720         * @return  An error code
 721         * @param[in] groupIndex            The group index
 722         * @param[in] itemIndex             The item index
 723         * @param[in] check    Set to @c true to select the item, @n
 724         *         else @c false
 725         * @exception E_SUCCESS   The method is successful.
 726         * @exception E_OUT_OF_RANGE           A specified input parameter is invalid.
 727         * @exception E_INVALID_OPERATION The item is disabled or the current state of the instance prohibits the execution of the specified operation.
 728         * @remarks
 729         *                       - This method works only when the annex style of the item allows selection.
 730         *                         This method does not work during the ITableViewItemProvider call-back procedure.
 731         *                       - This method should be called only after TableView items are created. If this method needs to be called early in the lifecycle of the
 732         *                       TableView, then UpdateTableView() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 733         */
 734         result SetItemChecked(int groupIndex, int itemIndex, bool check);
 735
 736         /**
 737         * Returns whether the item at the specified index is selected or not.
 738         *
 739         * @since 2.0
 740         *
 741         * @return @c true if the item is selected, @n
 742         *   else @c false
 743         * @param[in] groupIndex            The group index
 744         * @param[in] itemIndex             The item index
 745         * @exception E_SUCCESS                               The method is successful.
 746         * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
 747         * @remarks
 748         *                       - This method returns @c false, if the annex style of the item does not allow selection.
 749         *                       - This method should be called only after TableView items are created. If this method needs to be called early in the lifecycle of the
 750         *                       TableView, then UpdateTableView() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 751         */
 752         bool IsItemChecked(int groupIndex, int itemIndex) const;
 753
 754         /**
 755         * Enables or disables the item at the specified index.
 756         *
 757         * @since 2.0
 758         *
 759         * @return An error code
 760         * @param[in] groupIndex            The group index
 761         * @param[in] itemIndex             The item index
 762         * @param[in] enable    Set to @c true to enable the specified item, @n
 763         *         else @c false
 764         * @exception E_SUCCESS   The method is successful.
 765         * @exception E_OUT_OF_RANGE  A specified input parameter is invalid.
 766         * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation @b Since: @b 2.1.
 767         * @remarks
 768         *                       - This method does not work during the ITableViewItemProvider call-back procedure.
 769         *                       - This method should be called only after TableView items are created. If this method needs to be called early in the lifecycle of the
 770         *                       TableView, then UpdateTableView() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 771         */
 772         result SetItemEnabled(int groupIndex, int itemIndex, bool enable);
 773
 774         /**
 775         * Returns whether the item at the specified index is enabled or disabled.
 776         *
 777         * @since 2.0
 778         *
 779         * @return @c true if the item is enabled, @n
 780         *   else @c false
 781         * @param[in] groupIndex            The group index
 782         * @param[in] itemIndex             The item index
 783         * @exception E_SUCCESS                               The method is successful.
 784         * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
 785         * @remarks This method should be called only after TableView items are created. If this method needs to be called early in the lifecycle of the
 786         *                       TableView, then UpdateTableView() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 787         */
 788         bool IsItemEnabled(int groupIndex, int itemIndex) const;
 789
 790         /**
 791         * Counts the total number of groups.
 792         *
 793         * @since 2.0
 794         *
 795         * @return The total number of groups
 796         */
 797         int GetGroupCount(void) const;
 798
 799         /**
 800         * Counts all the items of the specified group.
 801         *
 802         * @since 2.0
 803         *
 804         * @return The total number of items in the specified group
 805         * @param[in] groupIndex   The group index
 806         * @exception E_SUCCESS                               The method is successful.
 807         * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
 808         */
 809         int GetItemCountAt(int groupIndex) const;
 810
 811         /**
 812         * Updates the specified item. @n
 813         * For instance, @c TABLE_VIEW_REFRESH_TYPE_ITEM_ADD is used when a new item needs to be added and
 814         * @c TABLE_VIEW_REFRESH_TYPE_ITEM_REMOVE is used when an item is deleted from the
 815         * table view. Moreover, @c TABLE_VIEW_REFRESH_TYPE_ITEM_MODIFY is used when the content of an existing item has changed and it needs to
 816         * be updated. @n
 817         * Note that calling the %RefreshAllItems() method with @c TABLE_VIEW_REFRESH_TYPE_ITEM_MODIFY invokes
 818         * IGroupedTableViewItemProvider::UpdateItem() or IGroupedTableViewItemProviderF::UpdateItem() for the given index in sequence.
 819         *
 820         * @since 2.0
 821         *
 822         * @return An error code
 823         * @param[in] groupIndex                    The group index
 824         * @param[in] itemIndex           The item index
 825         * @param[in] type                             The item to add, remove, or modify
 826         * @exception E_SUCCESS   The method is successful.
 827         * @exception E_OUT_OF_RANGE  A specified input parameter is invalid.
 828         * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation @b Since: @b 2.1.
 829         * @remarks
 830         *                       - If the specified @c itemIndex is @c -1, then the method is applied to the group item with the given index.
 831         *                       - Note that if @c TABLE_VIEW_REFRESH_TYPE_ITEM_REMOVE option is used to a group item, all the items in the
 832         *                       group (including the group item itself) are removed from the table view.
 833         *                       - This method does not work during the ITableViewItemProvider call-back procedure.
 834         */
 835         result RefreshItem(int groupIndex, int itemIndex, TableViewRefreshType type);
 836
 837         /**
 838         * Updates all items of the table view. @n
 839         * Note that calling the %RefreshAllItems() method invokes IGroupedTableViewItemProvider::UpdateItem() or
 840         * IGroupedTableViewItemProviderF::UpdateItem() for all loaded items.
 841         *
 842         * @since 2.1
 843         *
 844         * @return An error code
 845         * @exception E_SUCCESS The method is successful.
 846         * @exception E_INVALID_OPERATION The %GroupedTableView item provider is processing another request.
 847         */
 848         result RefreshAllItems(void);
 849
 850         /**
 851         * Updates all the items of a table view. @n
 852         * This method deletes all the items in the table view and invokes the methods of the item provider again to update the table view.
 853         *
 854         * @since 2.0
 855         *
 856         * @exception E_SUCCESS The method is successful.
 857         * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation @b Since: @b 2.1.
 858         * @remarks
 859         *                       - This method will delete all the items and recreate them, so it should not be called from the inside of
 860         *                       OnGroupedTableViewItemStateChanged() call-back as this leads to self deletion. If you need to update an Item, you should use RefreshItem() method.
 861         *                       - This method should not be called from IGroupedTableViewItemProvider implementation because of recursion.
 862         *                       - The specific error code can be accessed using the GetLastResult() method.
 863         */
 864         void UpdateTableView(void);
 865
 866         /**
 867         * Gets the index of the item at the specified position.
 868         *
 869         * @since 2.0
 870         *
 871         * @param[in] position    The position of the item
 872         * @param[out] groupIndex The group index of the item on specified position
 873         * @param[out] itemIndex  The item index of the item on specified position
 874         * @remarks
 875         *                       - This method sets both of groupIndex and itemIndex to @c -1 if no item is found at the given position.
 876         *                       - This method should be called only after TableView items are created. If this method needs to be called early in the lifecycle of the
 877         *                       TableView, then UpdateTableView() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 878         */
 879         void GetItemIndexFromPosition(const Tizen::Graphics::Point& position, int& groupIndex, int& itemIndex) const;
 880
 881         /**
 882         * Gets the index of the item at the specified position.
 883         *
 884         * @since 2.1
 885         *
 886         * @param[in] position    The position of the item
 887         * @param[out] groupIndex The group index of the item on specified position
 888         * @param[out] itemIndex  The item index of the item on specified position
 889         * @remarks
 890         *                       - This method sets both of groupIndex and itemIndex to @c -1 if no item is found at the given position.
 891         *                       - This method should be called only after TableView items are created. @n
 892         *                       If this method needs to be called early in the lifecycle of the TableView, then UpdateTableView() method should be called
 893         *                       explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 894         */
 895         void GetItemIndexFromPosition(const Tizen::Graphics::FloatPoint& position, int& groupIndex, int& itemIndex) const;
 896
 897         /**
 898         * Sets the color of a division line between items.
 899         *
 900         * @since 2.0
 901         *
 902         * @return An error code
 903         * @param[in] color    The division line color
 904         */
 905         void SetItemDividerColor(const Tizen::Graphics::Color& color);
 906
 907         /**
 908         * Gets the color of a division line between items.
 909         *
 910         * @since 2.0
 911         *
 912         * @return  The color of a division line
 913         */
 914         Tizen::Graphics::Color GetItemDividerColor(void) const;
 915
 916         /**
 917         * Sets the background color of this control.
 918         *
 919         * @since 2.0
 920         *
 921         * @param[in] color       The background color
 922         * @remarks The background bitmap has priority over the background color. When both the background bitmap and the background color are specified,
 923         *                       only the bitmap image is displayed.
 924         */
 925         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 926
 927         /**
 928         * Sets the scroll input handling mode.
 929         *
 930         * @since 2.0
 931         *
 932         * @param[in] mode  The scroll input handling mode
 933         * @see         GetScrollInputMode()
 934         */
 935         void SetScrollInputMode(ScrollInputMode mode);
 936
 937         /**
 938         * Gets the scroll input handling mode.
 939         *
 940         * @since 2.0
 941         *
 942         * @return     The scroll input handling mode
 943         * @see         SetScrollInputMode()
 944         */
 945         ScrollInputMode GetScrollInputMode(void) const;
 946
 947         /**
 948         * Gets the background color of this control.
 949         *
 950         * @since 2.0
 951         *
 952         * @return The background color
 953         */
 954         Tizen::Graphics::Color GetBackgroundColor(void) const;
 955
 956         /**
 957         * Scrolls the list contents by a specified number of pixels. @n
 958         * If the specified number is negative, it scrolls in the opposite direction in current scroll style.
 959         *
 960         * @since 2.1
 961         *
 962         * @return  An error code
 963         * @param[in]   pixel                                            The amount of pixels to scroll
 964         * @exception   E_SUCCESS                                The method is successful.
 965         * @exception   E_OUT_OF_RANGE           The specified @c pixel is out of range.
 966         * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation
 967         * @remarks
 968         *                       - If you call ScrollByPixel() with negative @c pixel when position of scroll is already top of contents then it
 969         *                       will return @c E_OUT_OF_RANGE. @n
 970         *                       Likewise, in case of positive @c pixel on the bottom position of scroll it will also return @c E_OUT_OF_RANGE.
 971         *                       - This method does not work during the ITableViewItemProvider call-back procedure.
 972         */
 973         result ScrollByPixel(int pixel);
 974
 975         /**
 976         * Scrolls the list contents by a specified number of pixels. @n
 977         * If the specified number is negative, it scrolls in the opposite direction in current scroll style.
 978         *
 979         * @since 2.1
 980         *
 981         * @return  An error code
 982         * @param[in]   pixel                                            The amount of pixels to scroll
 983         * @exception   E_SUCCESS                                The method is successful.
 984         * @exception   E_OUT_OF_RANGE           The specified @c pixel is out of range.
 985         * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation
 986         * @remarks
 987         *                       - If you call ScrollByPixel() with negative @c pixel when position of scroll is already top of contents then
 988         *                       it will return @c E_OUT_OF_RANGE. @n
 989         *                       Likewise, in case of positive @c pixel on the bottom position of scroll it will also return @c E_OUT_OF_RANGE.
 990         *                       - This method does not work during the ITableViewItemProvider call-back procedure.
 991         */
 992         result ScrollByPixel(float pixel);
 993
 994         /**
 995         * Gets the current scroll position
 996         *
 997         * @since 2.1
 998         */
 999         int GetCurrentScrollPosition(void) const;
1000
1001         /**
1002         * Gets the current scroll position
1003         *
1004         * @since 2.1
1005         */
1006         float GetCurrentScrollPositionF(void) const;
1007
1008         /*
1009         * Enables or disables the scroll of GroupedTableView items.
1010         *
1011         * @since 2.0
1012         */
1013         void SetScrollEnabled(bool enable);
1014
1015         /*
1016         * Checks whether the scroll is enabled or disabled.
1017         *
1018         * @since 2.0
1019         */
1020         bool IsScrollEnabled(void) const;
1021
1022         /**
1023         * Begins the reordering mode.
1024         *
1025         * @since                        2.1
1026         *
1027         * @see                           IGroupedTableViewItemEventListener::OnGroupedTableViewItemReordered()
1028         */
1029         void BeginReorderingMode(void);
1030
1031         /**
1032         * Ends the reordering mode.
1033         *
1034         * @since                        2.1
1035         *
1036         * @see                           IGroupedTableViewItemEventListener::OnGroupedTableViewItemReordered()
1037         */
1038         void EndReorderingMode(void);
1039
1040         /**
1041         * Checks whether the %GroupedTableView control is in reordering mode.
1042         *
1043         * @since                        2.1
1044         *
1045         * @return                        @c true if the %GroupedTableView is in reordering mode, @n
1046         *                                        else @c false
1047         */
1048         bool IsInReorderingMode(void) const;
1049
1050         /**
1051         * Opens the context item at a specified index.
1052         *
1053         * @since 2.1
1054         *
1055         * @return  An error code
1056         * @param[in] groupIndex The group index
1057         * @param[in] itemIndex  The item index
1058         * @exception E_SUCCESS   The method is successful.
1059         * @exception E_OUT_OF_RANGE                A specified input parameter is invalid.
1060         * @exception E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
1061         */
1062         result OpenContextItem(int groupIndex, int itemIndex);
1063
1064         /**
1065         * Closes the context item at a specified index.
1066         *
1067         * @since 2.1
1068         *
1069         * @return  An error code
1070         * @param[in] groupIndex The group index
1071         * @param[in] itemIndex  The item index
1072         * @exception E_SUCCESS   The method is successful.
1073         * @exception E_OUT_OF_RANGE                A specified input parameter is invalid.
1074         * @exception E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
1075         */
1076         result CloseContextItem(int groupIndex, int itemIndex);
1077
1078         /**
1079         * Checks whether the context item at a specified index has been opened or not.
1080         *
1081         * @since 2.1
1082         *
1083         * @return @c true if the context item has been opened, @n
1084         *                 else @c false
1085         * @param[in] groupIndex The group index
1086         * @param[in] itemIndex  The item index
1087         * @exception E_SUCCESS           The method is successful.
1088         * @exception E_OUT_OF_RANGE  A specified input parameter is invalid.
1089         */
1090         bool IsContextItemOpened(int groupIndex, int itemIndex) const;
1091
1092 private:
1093         friend class _TableViewImpl;
1094
1095         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1096         GroupedTableView(const GroupedTableView& rhs);
1097
1098         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1099         GroupedTableView& operator =(const GroupedTableView& rhs);
1100 }; // GroupedTableView
1101
1102 }}} // Tizen::Ui::Controls
1103
1104 #endif  // _FUI_CTRL_GROUPED_TABLE_VIEW_H_