inc/FUiCtrlGroupedListView.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FUiCtrlGroupedListView.h
  20  * @brief       This is the header file for the %GroupedListView class.
  21  *
  22  * This header file contains the declarations of the %GroupedListView class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_GROUPED_LIST_VIEW_H_
  26 #define _FUI_CTRL_GROUPED_LIST_VIEW_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FGrpRectangle.h>
  31 #include <FUiControl.h>
  32 #include <FUiContainer.h>
  33 #include <FUiCtrlGroupedListViewTypes.h>
  34 #include <FUiCtrlIFastScrollListener.h>
  35 #include <FUiCtrlIGroupedListViewItemEventListener.h>
  36 #include <FUiCtrlIGroupedListViewItemProvider.h>
  37 #include <FUiCtrlIScrollEventListener.h>
  38 #include <FUiCtrlListViewTypes.h>
  39 #include <FUiIUiLinkEventListener.h>
  40
  41 namespace Tizen { namespace Ui { namespace Controls
  42 {
  43
  44 class _GroupedListViewImpl;
  45
  46 /**
  47  * @class       GroupedListView
  48  * @brief   This class defines the common behavior of a %GroupedListView control.
  49  *
  50  * @since       2.0
  51  *
  52  * The %GroupedListView class displays a list of grouped items in a list. The items in a GroupedList control consist of groups and
  53  * items. A group represents the grouped items and is placed at the first level. Each group consists of simple or custom items.
  54  * Therefore, items are uniquely identified with two indexes: group index and item index.
  55  *
  56  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_listviews.htm">ListViews</a>.
  57  *
  58  * The following example demonstrates how to use the %GroupedListView class.
  59  *
  60  *
  61  * @code
  62 //Sample code for GroupedListViewSample.h
  63
  64 #include <FUi.h>
  65
  66 class CustomGroupedListElement;
  67
  68 class GroupedListViewSample
  69         : public Tizen::Ui::Controls::Form
  70         , public Tizen::Ui::Controls::IGroupedListViewItemEventListener
  71         , public Tizen::Ui::Controls::IGroupedListViewItemProvider
  72 {
  73 public:
  74         GroupedListViewSample(void)
  75         : __pGroupedListView(null)
  76         , __pCustomGroupedListElement(null){}
  77
  78         bool Initialize(void);
  79         virtual result OnInitializing(void);
  80         virtual result OnTerminating(void);
  81
  82         // IGroupedListViewItemEventListener
  83         virtual void OnGroupedListViewContextItemStateChanged(Tizen::Ui::Controls::GroupedListView &listView, int groupIndex, int itemIndex, int elementId, Tizen::Ui::Controls::ListContextItemStatus state);
  84         virtual void OnGroupedListViewItemStateChanged(Tizen::Ui::Controls::GroupedListView &listView, int groupIndex, int itemIndex, int elementId, Tizen::Ui::Controls::ListItemStatus state);
  85         virtual void OnGroupedListViewItemSwept(Tizen::Ui::Controls::GroupedListView &listView, int groupIndex,  int itemIndex, Tizen::Ui::Controls::SweepDirection direction);
  86
  87         // IGroupedListViewItemProvider
  88         virtual int GetGroupCount(void);
  89         virtual int GetItemCount(int groupIndex);
  90         virtual Tizen::Ui::Controls::ListItemBase* CreateItem(int groupIndex, int itemIndex, int itemWidth);
  91         virtual Tizen::Ui::Controls::GroupItem* CreateGroupItem(int groupIndex, int itemWidth);
  92         virtual bool DeleteItem(int groupIndex, int itemIndex, Tizen::Ui::Controls::ListItemBase* pItem, int itemWidth);
  93         virtual bool DeleteGroupItem(int groupIndex, Tizen::Ui::Controls::GroupItem* pItem, int itemWidth);
  94
  95 private:
  96         static const int ID_FORMAT_STRING = 100;
  97         static const int ID_FORMAT_BITMAP = 101;
  98         static const int ID_FORMAT_CUSTOM = 102;
  99         static const int ID_CONTEXT_ITEM_1 = 103;
 100         static const int ID_CONTEXT_ITEM_2 = 104;
 101
 102         Tizen::Graphics::Bitmap* __pHome;
 103         Tizen::Graphics::Bitmap* __pMsg;
 104         Tizen::Graphics::Bitmap* __pAlarm;
 105         Tizen::Graphics::Bitmap* __pCall;
 106
 107         Tizen::Ui::Controls::GroupedListView* __pGroupedListView;
 108         Tizen::Ui::Controls::ListContextItem* __pItemContext;
 109         CustomGroupedListElement* __pCustomGroupedListElement;
 110 };
 111  *      @endcode
 112  *
 113  *      @code
 114 //Sample code for GroupedListViewSample.cpp
 115 #include <FApp.h>
 116 #include <FGraphics.h>
 117
 118 #include "GroupedListViewSample.h"
 119
 120 using namespace Tizen::App;
 121 using namespace Tizen::Base;
 122 using namespace Tizen::Graphics;
 123 using namespace Tizen::Ui::Controls;
 124
 125 class CustomGroupedListElement
 126         : public ICustomElement
 127 {
 128 public:
 129         bool
 130         OnDraw(Canvas& canvas, const Rectangle& rect, ListItemDrawingStatus itemStatus)
 131         {
 132                 Tizen::Graphics::Font font;
 133                 font.Construct(FONT_STYLE_PLAIN, 15);
 134                 canvas.SetFont(font);
 135                 canvas.SetLineWidth(3);
 136                 canvas.SetForegroundColor(Color::GetColor(COLOR_ID_GREEN));
 137
 138                 if (canvas.DrawRectangle(rect) != E_SUCCESS)
 139                 {
 140                         return false;
 141                 }
 142
 143                 if (canvas.DrawText(Point(rect.x+10, rect.y+15), L"Custom") != E_SUCCESS)
 144                 {
 145                         return false;
 146                 }
 147
 148                 return true;
 149         }
 150 };
 151
 152 bool
 153 GroupedListViewSample::Initialize(void)
 154 {
 155         Construct(FORM_STYLE_NORMAL);
 156         return true;
 157 }
 158
 159 result
 160 GroupedListViewSample::OnInitializing(void)
 161 {
 162         result r = E_SUCCESS;
 163
 164         // Creates an instance of IconListView
 165         __pGroupedListView = new GroupedListView();
 166         __pGroupedListView->Construct(Rectangle(0, 0, GetClientAreaBounds().width, GetClientAreaBounds().height), GROUPED_LIST_VIEW_STYLE_INDEXED, true, true);
 167         __pGroupedListView->SetItemProvider(*this);
 168         __pGroupedListView->AddGroupedListViewItemEventListener(*this);
 169
 170         // Adds the icon list view to the form
 171         AddControl(*__pGroupedListView);
 172
 173         // Creates an instance of ListContextItem
 174         __pItemContext = new ListContextItem();
 175         __pItemContext->Construct();
 176         __pItemContext->AddElement(ID_CONTEXT_ITEM_1, "Test1");
 177         __pItemContext->AddElement(ID_CONTEXT_ITEM_2, "Test2");
 178
 179         // Gets instances of Bitmap
 180         AppResource* pAppResource = Application::GetInstance()->GetAppResource();
 181         __pHome = pAppResource->GetBitmapN(L"tizen.png");
 182         __pMsg = pAppResource->GetBitmapN(L"tizen.png");
 183         __pAlarm = pAppResource->GetBitmapN(L"tizen.png");
 184         __pCall = pAppResource->GetBitmapN(L"tizen.png");
 185
 186         // Creates an instance of CustomGroupedListElement
 187         __pCustomGroupedListElement = new CustomGroupedListElement();
 188
 189         return r;
 190 }
 191
 192 result
 193 GroupedListViewSample::OnTerminating(void)
 194 {
 195         result r = E_SUCCESS;
 196
 197         // Deallocates bitmaps
 198         delete __pHome;
 199         delete __pMsg;
 200         delete __pAlarm;
 201         delete __pCall;
 202
 203         // Deallocates the item context
 204         delete __pItemContext;
 205
 206         return r;
 207 }
 208
 209 void
 210 GroupedListViewSample::OnGroupedListViewItemStateChanged(GroupedListView &listView, int groupIndex, int itemIndex, int elementId, ListItemStatus state)
 211 {
 212         switch (elementId)
 213         {
 214         case ID_FORMAT_STRING:
 215                 {
 216                         // ....
 217                 }
 218                 break;
 219         case ID_FORMAT_BITMAP:
 220                 {
 221                         // ....
 222                 }
 223                 break;
 224         default:
 225                 break;
 226         }
 227 }
 228
 229 void
 230 GroupedListViewSample::OnGroupedListViewContextItemStateChanged(GroupedListView &listView, int groupIndex, int itemIndex, int elementId, ListContextItemStatus state)
 231 {
 232         switch (elementId)
 233         {
 234         case ID_CONTEXT_ITEM_1:
 235                 {
 236                         // ....
 237                 }
 238                 break;
 239         case ID_CONTEXT_ITEM_2:
 240                 {
 241                         // ....
 242                 }
 243                 break;
 244         default:
 245                 break;
 246         }
 247 }
 248
 249 // IGroupedListViewItemEventListener
 250 void
 251 GroupedListViewSample::OnGroupedListViewItemSwept(GroupedListView &listView, int groupIndex,  int itemIndex, SweepDirection direction)
 252 {
 253         // ....
 254 }
 255
 256 int
 257 GroupedListViewSample::GetGroupCount(void)
 258 {
 259         return 3;
 260 }
 261
 262 int
 263 GroupedListViewSample::GetItemCount(int groupIndex)
 264 {
 265         int itemCount = 0;
 266         switch (groupIndex)
 267         {
 268         case 0:
 269                 {
 270                         itemCount = 7;
 271                 }
 272                 break;
 273         case 1:
 274                 {
 275                         itemCount = 5;
 276                 }
 277                 break;
 278         case 2:
 279                 {
 280                         itemCount = 3;
 281                 }
 282                 break;
 283         default:
 284                 break;
 285         }
 286
 287         return itemCount;
 288 }
 289
 290 // IGroupedListViewItemProvider
 291 GroupItem*
 292 GroupedListViewSample::CreateGroupItem(int groupIndex, int itemWidth)
 293 {
 294         String text("Group ");
 295         text.Append(groupIndex+1);
 296
 297         GroupItem* pItem = new GroupItem();
 298         pItem->Construct(Dimension(itemWidth, 40));
 299         pItem->SetElement(text, null);
 300
 301         return pItem;
 302 }
 303
 304 ListItemBase*
 305 GroupedListViewSample::CreateItem(int groupIndex, int itemIndex, int itemWidth)
 306 {
 307         // Creates an instance of CustomItem
 308         CustomItem* pItem = new CustomItem();
 309         ListAnnexStyle style = LIST_ANNEX_STYLE_NORMAL;
 310         pItem->Construct(Dimension(itemWidth, 100), style);
 311
 312         switch (itemIndex % 4)
 313         {
 314         case 0:
 315                 {
 316                         style = LIST_ANNEX_STYLE_NORMAL;
 317                         pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pHome, null, null);
 318                         pItem->AddElement(Rectangle(150, 25, 150, 50), ID_FORMAT_STRING, L"Home", true);
 319                 }
 320                 break;
 321         case 1:
 322                 {
 323                         style = LIST_ANNEX_STYLE_MARK;
 324                         pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pMsg, null, null);
 325                         pItem->AddElement(Rectangle(150, 25, 150, 50), ID_FORMAT_STRING, L"Msg", true);
 326                 }
 327                 break;
 328         case 2:
 329                 {
 330                         style = LIST_ANNEX_STYLE_ONOFF_SLIDING;
 331                         pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pAlarm, null, null);
 332                         pItem->AddElement(Rectangle(150, 25, 150, 50), ID_FORMAT_STRING, L"Alarm", true);
 333                 }
 334                 break;
 335         case 3:
 336                 {
 337                         style = LIST_ANNEX_STYLE_DETAILED;
 338                         pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pCall, null, null);
 339                         pItem->AddElement(Rectangle(150, 25, 150, 50), ID_FORMAT_STRING, L"Call", true);
 340                 }
 341                 break;
 342         default:
 343                 break;
 344         }
 345         pItem->AddElement(Rectangle(360, 10, 180, 80), ID_FORMAT_CUSTOM, *(static_cast<ICustomElement *>(__pCustomGroupedListElement)));
 346         pItem->SetContextItem(__pItemContext);
 347
 348         return pItem;
 349 }
 350
 351 bool
 352 GroupedListViewSample::DeleteItem(int groupIndex, int itemIndex, ListItemBase* pItem, int itemWidth)
 353 {
 354         delete pItem;
 355         pItem = null;
 356         return true;
 357 }
 358
 359 bool
 360 GroupedListViewSample::DeleteGroupItem(int groupIndex, GroupItem* pItem, int itemWidth)
 361 {
 362         delete pItem;
 363         pItem = null;
 364         return true;
 365 }
 366  * @endcode
 367  *
 368  */
 369
 370
 371 class _OSP_EXPORT_ GroupedListView
 372         : public Tizen::Ui::Control
 373 {
 374 public:
 375         /**
 376          * The object is not fully constructed after this constructor is
 377          * called. For full construction, the Construct() method must be
 378          * called right after calling this constructor.
 379          *
 380          * @since       2.0
 381          */
 382         GroupedListView(void);
 383
 384         /**
 385          * This destructor overrides Tizen::Base::Object::~Object().
 386          *
 387          * @since       2.0
 388          */
 389         virtual ~GroupedListView(void);
 390
 391         /**
 392          * @if OSPDEPREC
 393          * Initializes this instance of %GroupedListView with the specified parameters.
 394          *
 395          * @brief <i> [Deprecated]  </i>
 396          * @deprecated  This method is deprecated.
 397          * @since       2.0
 398          *
 399          * @return  An error code
 400          * @param[in]   rect                            An instance of the Graphics::Rectangle class
 401          *                                  This instance represents the x and y coordinates of the top-left corner of the created
 402          *                                                                      %GroupedListView control along with the width and height.
 403          * @param[in]   style                           The style of the %GroupedListView control
 404          * @param[in]   itemDivider                     Set to @c true to display an item divider, @n
 405          *                                                                      else @c false
 406          * @param[in]   fastScroll                      Set to @c true to use the fast scroll, @n
 407          *                                                                      else @c false
 408          * @exception   E_SUCCESS                       The method is successful.
 409          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 410          *                                                              Either the @c rect.width or @c rect.height parameter has a negative value.
 411          * @exception   E_SYSTEM                        A system error has occurred.
 412          * @endif
 413          */
 414         result Construct(const Tizen::Graphics::Rectangle& rect, GroupedListViewStyle style, bool itemDivider = true, bool fastScroll = false);
 415
 416         /**
 417          * Initializes this instance of %GroupedListView with the specified parameters.
 418          *
 419          * @since 2.0
 420          *
 421          * @return  An error code
 422          * @param[in]   rect                            An instance of the Graphics::Rectangle class
 423          *                                  This instance represents the x and y coordinates of the top-left corner of the created
 424          *                                                                      %GroupedListView control along with the width and height.
 425          * @param[in]   style                           The style of the %GroupedListView control
 426          * @param[in]   itemDivider                     Set to @c true to display an item divider, @n
 427          *                                                                      else @c false
 428          * @param[in]   scrollStyle                     Set to scroll style
 429          * @exception   E_SUCCESS                       The method is successful.
 430          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 431          *                                                              Either the @c rect.width or @c rect.height parameter has a negative value.
 432          * @exception   E_SYSTEM                        A system error has occurred.
 433          */
 434         result Construct(const Tizen::Graphics::Rectangle& rect, GroupedListViewStyle style, bool itemDivider, ListScrollStyle scrollStyle);
 435
 436         /**
 437          * Sets the item provider that creates and deletes items from the list.
 438          *
 439          * @since       2.0
 440          *
 441          * @return              An error code
 442          * @param[in]   provider                        The item provider to create and delete items
 443          * @exception   E_SUCCESS                       The method is successful.
 444          * @exception   E_SYSTEM                        A system error has occurred.
 445          * @remarks     If an item provider is not set for the list, the list does not work. @n
 446          *                      A provider should be allocated on a heap memory.
 447          */
 448         result SetItemProvider(IGroupedListViewItemProvider& provider);
 449
 450         /**
 451          * Adds an IGroupedListViewItemEventListener instance that listens to the state changes of the list view items. @n
 452          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 453          *
 454          * @since       2.0
 455          *
 456          * @param[in]   listener                        The event listener to be added
 457          */
 458         void AddGroupedListViewItemEventListener(IGroupedListViewItemEventListener& listener);
 459
 460         /**
 461          * Removes an IGroupedListViewItemEventListener instance that listens to the state changes of the list view items. @n
 462          * The removed listener cannot listen to events when they are fired.
 463          *
 464          * @since       2.0
 465          *
 466          * @param[in]   listener                        The event listener to be removed
 467          */
 468         void RemoveGroupedListViewItemEventListener(IGroupedListViewItemEventListener& listener);
 469
 470         /**
 471          * Adds an IFastScrollListener instance that listens to the state changes of a fast scroll. @n
 472          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 473          *
 474          * @since       2.0
 475          *
 476          * @param[in]   listener                        The event listener to be added
 477          */
 478         void AddFastScrollListener(IFastScrollListener& listener);
 479
 480         /**
 481          * Removes an IFastScrollListener instance that listens to the state changes of a fast scroll. @n
 482          * The removed listener cannot listen to events when they are fired.
 483          *
 484          * @since       2.0
 485          *
 486          * @param[in]   listener                        The event listener to be removed
 487          */
 488         void RemoveFastScrollListener(IFastScrollListener& listener);
 489
 490         /**
 491          * Adds an IScrollEventListener instance that listens to the state changes of a scroll event. @n
 492          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 493          *
 494          * @since       2.0
 495          *
 496          * @param[in]   listener                        The event listener to be added
 497          * @see       IScrollEventListener::OnScrollEndReached()
 498          * @see       RemoveScrollEventListener()
 499          */
 500         void AddScrollEventListener(IScrollEventListener& listener);
 501
 502         /**
 503          * Removes an IScrollEventListener instance that listens to the state changes of a scroll event. @n
 504          * The removed listener cannot listen to events when they are fired.
 505          *
 506          * @since       2.0
 507          *
 508          * @param[in]   listener                        The event listener to be removed
 509          * @see     IScrollEventListener::OnScrollEndReached()
 510          * @see     AddScrollEventListener()
 511          */
 512         void RemoveScrollEventListener(IScrollEventListener& listener);
 513
 514         /**
 515          * Adds a link event listener.
 516          *
 517          * @since   2.0
 518          *
 519          * @param[in]   listener                        The event listener to be added
 520          * @remarks     The added listener is notified when a link is selected by the user.
 521          *
 522          * @see     RemoveUiLinkEventListener()
 523          */
 524         void AddUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
 525
 526         /**
 527          * Removes the specified link event listener.
 528          * The removed listener cannot listen to events when they are fired.
 529          *
 530          * @since       2.0
 531          *
 532          * @param[in]   listener                        The event listener to be removed
 533          * @see         AddUiLinkEventListener()
 534          */
 535         void RemoveUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
 536
 537         /**
 538          * Enables or disables the sweep event.
 539          *
 540          * @since       2.0
 541          *
 542          * @return      An error code
 543          * @param[in]   enable              Set to @c true to enable the item sweep, @n
 544          *                                                                      else @c false
 545          * @exception   E_SUCCESS           The method is successful.
 546          * @exception   E_SYSTEM            A system error has occurred.
 547          */
 548         result SetSweepEnabled(bool enable);
 549
 550         /**
 551          * Sets the index list of the fast scroll.
 552          *
 553          * @since       2.0
 554          *
 555          * @return      An error code
 556          * @param[in]   text                            The text of the index
 557          * @param[in]   useSearchIcon           Set to @c true to display the magnifying icon, @n
 558          *                                                                      else @c false
 559          * @exception   E_SUCCESS                       The method is successful.
 560          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 561          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 562          * @exception   E_SYSTEM                        A system error has occurred.
 563          */
 564         result SetFastScrollIndex(const Tizen::Base::String& text, bool useSearchIcon);
 565
 566         /**
 567          * Gets the group and item indexes of the top item.
 568          *
 569          * @since       2.0
 570          *
 571          * @return      An error code
 572          * @param[out]  groupIndex          The group index
 573          * @param[out]  itemIndex           The item index
 574          * @exception   E_SUCCESS           The method is successful.
 575          * @exception   E_SYSTEM                        A system error has occurred.
 576          */
 577         result GetTopDrawnItemIndex(int& groupIndex, int& itemIndex) const;
 578
 579         /**
 580          * Gets the group and item indexes of the bottom item.
 581          *
 582          * @since       2.0
 583          *
 584          * @return      An error code
 585          * @param[out]  groupIndex          The group index
 586          * @param[out]  itemIndex           The item index
 587          * @exception   E_SUCCESS           The method is successful.
 588          * @exception   E_SYSTEM            A system error has occurred.
 589          */
 590         result GetBottomDrawnItemIndex(int& groupIndex, int& itemIndex) const;
 591
 592
 593         /**
 594          * Scrolls to the item at the specified index. @n
 595          * The specified item is drawn at the top of the %GroupedListView control.
 596          *
 597          * @since       2.0
 598          *
 599          * @return  An error code
 600          * @param[in] groupIndex            The group index
 601          * @param[in] itemIndex             The item index
 602          * @exception E_SUCCESS             The method is successful.
 603          * @exception E_OUT_OF_RANGE        A specified input parameter is invalid.
 604          * @exception E_SYSTEM              A system error has occurred.
 605          */
 606         result ScrollToItem(int groupIndex, int itemIndex);
 607
 608         /**
 609          * Scrolls to the item at the specified index. @n
 610          * The specified item is drawn at the position specified by the item alignment.
 611          *
 612          * @since       2.0
 613          *
 614          * @return  An error code
 615          * @param[in] groupIndex            The group index
 616          * @param[in] itemIndex             The item index
 617          * @param[in] itemAlignment                     The item alignment
 618          * @exception E_SUCCESS             The method is successful.
 619          * @exception E_OUT_OF_RANGE        A specified input parameter is invalid.
 620          * @exception E_SYSTEM              A system error has occurred.
 621          */
 622         result ScrollToItem(int groupIndex, int itemIndex, ListScrollItemAlignment itemAlignment);
 623
 624         /**
 625          * Checks or unchecks the item at the specified index.
 626          *
 627          * @since       2.0
 628          *
 629          * @return  An error code
 630          * @param[in]   groupIndex                      The group index of the item to check
 631          * @param[in]   itemIndex                       The index of the item to check
 632          * @param[in]   check                           Set to @c true to select the item, @n
 633          *                                                                      else @c false
 634          * @exception   E_SUCCESS                       The method is successful.
 635          * @exception   E_OUT_OF_RANGE          A specified input parameter is invalid.
 636          * @exception   E_INVALID_OPERATION     The item is disabled.
 637          * @exception   E_SYSTEM                        A system error has occurred.
 638          * @remarks     This method works only when the annex style of the item allows selection.
 639          */
 640         result SetItemChecked(int groupIndex, int itemIndex, bool check);
 641
 642         /**
 643          * Checks whether the item at the specified index is selected.
 644          *
 645          * @since       2.0
 646          *
 647          * @return      @c true if the item is selected, @n
 648          *                      else @c false
 649          * @param[in]   groupIndex                      The group index
 650          * @param[in]   itemIndex                       The item index
 651          * @remarks     This method returns @c false, if the annex style of the item does not allow selection.
 652          */
 653         bool IsItemChecked(int groupIndex, int itemIndex) const;
 654
 655         /**
 656          * Enables or disables the item at the specified index.
 657          *
 658          * @since       2.0
 659          *
 660          * @return      An error code
 661          * @param[in]   groupIndex                      The group index
 662          * @param[in]   itemIndex                       The item index
 663          * @param[in]   enable                          Set to @c true to enable the specified item, @n
 664          *                                                                      else @c false
 665          * @exception   E_SUCCESS                       The method is successful.
 666          * @exception   E_OUT_OF_RANGE          A specified input parameter is invalid.
 667          * @exception   E_SYSTEM                        A system error has occurred.
 668          * @remarks     This method can only be used when the annex style of the list allows selection.
 669          */
 670         result SetItemEnabled(int groupIndex, int itemIndex, bool enable);
 671
 672         /**
 673          * Checks whether the item at the specified index is enabled or disabled.
 674          *
 675          * @since       2.0
 676          *
 677          * @return      @c true if the item is enabled, @n
 678          *                      else @c false
 679          * @param[in]   groupIndex                      The group index
 680          * @param[in]   itemIndex                       The item index
 681          */
 682         bool IsItemEnabled(int groupIndex, int itemIndex) const;
 683
 684         /**
 685          * Counts the total number of groups.
 686          *
 687          * @since       2.0
 688          *
 689          * @return      The total number of groups
 690          */
 691         int GetGroupCount(void) const;
 692
 693         /**
 694          * Counts all the items of the specified group.
 695          *
 696          * @since       2.0
 697          *
 698          * @return      The total number of items in the specified group
 699          * @param[in]   groupIndex                      The group index
 700          */
 701         int GetItemCountAt(int groupIndex) const;
 702
 703         /**
 704          * Shows the description text of the specified item.
 705          *
 706          * @since       2.0
 707          *
 708          * @return      An error code
 709          * @param[in]   groupIndex                      The group index of the item
 710          * @param[in]   itemIndex                       The index of the item
 711          * @exception   E_SUCCESS                       The method is successful.
 712          * @exception   E_OUT_OF_RANGE          A specified input parameter is invalid.
 713          * @exception   E_SYSTEM                        A system error has occurred.
 714          * @remarks     If no description text is set for the item at the specified index, it is not displayed.
 715          *
 716          */
 717         result ShowItemDescriptionText(int groupIndex, int itemIndex);
 718
 719         /**
 720          * Hides the description text of the specified item.
 721          *
 722          * @since       2.0
 723          *
 724          * @return      An error code
 725          * @param[in]   groupIndex                      The group index of the item
 726          * @param[in]   itemIndex                       The index of the item
 727          * @exception   E_SUCCESS                       The method is successful.
 728          * @exception   E_OUT_OF_RANGE          A specified input parameter is invalid.
 729          * @exception   E_SYSTEM                        A system error has occurred.
 730          */
 731         result HideItemDescriptionText(int groupIndex, int itemIndex);
 732
 733         /**
 734          * Updates the specified item. @n
 735          * For instance, LIST_REFRESH_TYPE_ITEM_ADD is used when a new item needs to be added and LIST_REFRESH_TYPE_ITEM_REMOVE is used when an item is deleted from the
 736          * list. Moreover, LIST_REFRESH_TYPE_ITEM_MODIFY is used when the content of an existing item has changed and it needs to be updated. @n
 737          * Note that calling this method with LIST_REFRESH_TYPE_ITEM_MODIFY invokes item provider's DeleteItem() and CreateItem() for the given index in sequence.
 738          *
 739          * @since       2.0
 740          *
 741          * @return      An error code
 742          * @param[in]   groupIndex                      The group index
 743          * @param[in]   itemIndex                       The item index
 744          * @param[in]   type                The item to be added, removed, or modified
 745          * @exception   E_SUCCESS                       The method is successful.
 746          * @exception   E_OUT_OF_RANGE          A specified input parameter is invalid.
 747          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
 748          * @exception   E_SYSTEM            A system error has occurred.
 749          * @remarks     If the specified itemIndex is -1, then the method is applied to the group item with the given index. @n
 750          *                      Note that if LIST_REFRESH_TYPE_ITEM_REMOVE option is used to a group item, all the items in the group (including the group item itself) are
 751          *                      removed from the list.
 752          * @remarks     This method internally calls Invalidate(), so you do not need to call them to update the screen.
 753          */
 754         result RefreshList(int groupIndex, int itemIndex, ListRefreshType type);
 755
 756         /**
 757          * Refreshes the specified item's element.
 758          *
 759          * @since 2.0
 760          *
 761          * @return  An error code
 762          * @param[in]   groupIndex                      The group index
 763          * @param[in]   itemIndex                       The item index
 764          * @param[in]   elementId                       The item element ID
 765          * @exception   E_SUCCESS                       The method is successful.
 766          * @exception   E_OUT_OF_RANGE          A specified input parameter is invalid.
 767          * @exception   E_SYSTEM            A system error has occurred.
 768          * @remarks  This method internally calls Invalidate(), so you do not need to call them to update the screen.
 769          */
 770         result RefreshList(int groupIndex, int itemIndex, int elementId);
 771
 772         /**
 773          * Updates all the items of a list.
 774          *
 775          * @since       2.0
 776          *
 777          * @return      An error code
 778          * @exception   E_SUCCESS                       The method is successful.
 779          * @exception   E_SYSTEM                        A system error has occurred.
 780          * @remarks     This method clears all the items in the list and invokes the methods of the item provider again to update the list.
 781          */
 782         result UpdateList(void);
 783
 784         /**
 785          * Gets the index of the item at the specified position.
 786          *
 787          * @since       2.0
 788          *
 789          * @return      An error code
 790          * @param[in]   x                                       The X position of the item
 791          * @param[in]   y                                       The Y position of the item
 792          * @param[out]  groupIndex                      The index of the group that the item belongs to
 793          * @param[out]  itemIndex                       The index of the item
 794          * @exception   E_SUCCESS                       The method is successful.
 795          * @exception   E_SYSTEM                        A system error has occurred, or @n
 796          *                                                                      there is no item at the specified position.
 797          */
 798         result GetItemIndexFromPosition(int x, int y, int& groupIndex, int& itemIndex) const;
 799
 800         /**
 801          * Gets the index of the item at the specified position.
 802          *
 803          * @since       2.0
 804          *
 805          * @return      An error code
 806          * @param[in]   position                        The position of the item
 807          * @param[out]  groupIndex                      The index of the group that the item belongs to
 808          * @param[out]  itemIndex                       The index of the item
 809          * @exception   E_SUCCESS                       The method is successful.
 810          * @exception   E_SYSTEM            A system error has occurred, or @n
 811          *                                                                      there is no item at the specified position.
 812          */
 813         result GetItemIndexFromPosition(const Tizen::Graphics::Point& position, int& groupIndex, int& itemIndex) const;
 814
 815         /**
 816          * Gets the index of the item and ID of the element at the specified position.
 817          *
 818          * @since       2.0
 819          *
 820          * @return  An error code
 821          * @param[in]  x                    The X position of the item
 822          * @param[in]  y                    The Y position of the item
 823          * @param[out] groupIndex           The index of the group that the item belongs to
 824          * @param[out] itemIndex            The index of the item
 825          * @param[out] elementId            The ID of the element
 826          * @exception  E_SUCCESS            The method is successful.
 827          * @exception  E_SYSTEM             A system error has occurred, or
 828          *                                                                  there is no item at the specified position.
 829          * @remarks     @c groupIndex and @c itemIndex are -1 when there is no list item at the specified position.
 830          * @remarks     @c elementId is -1 when there is no element at the specified position
 831          */
 832         result GetItemIndexFromPosition(int x, int y, int& groupIndex, int& itemIndex, int& elementId) const;
 833
 834         /**
 835          * Gets the index of the item and ID of the element at the specified position.
 836          *
 837          * @since       2.0
 838          *
 839          * @return  An error code
 840          * @param[in]  position             The position of the point
 841          * @param[out] groupIndex           The index of the group that the item belongs to
 842          * @param[out] itemIndex            The index of the item
 843          * @param[out] elementId            The ID of the element
 844          * @exception  E_SUCCESS            The method is successful.
 845          * @exception  E_SYSTEM             A system error has occurred, or
 846          *                                                                  there is no item at the specified position.
 847          * @remarks     @c groupIndex and @c itemIndex are -1 when there is no list item at the specified position.
 848          * @remarks  @c elementId is -1 when there is no element at the specified position
 849          */
 850         result GetItemIndexFromPosition(const Tizen::Graphics::Point& position, int& groupIndex, int& itemIndex, int& elementId) const;
 851
 852         /**
 853          * Sets the color of a section.
 854          *
 855          * @since       2.0
 856          *
 857          * @return      An error code
 858          * @param[in]   color                           The section color
 859          * @exception   E_SUCCESS                       The method is successful.
 860          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation (this control cannot be displayed).
 861          * @exception   E_SYSTEM                        A system error has occurred.
 862          * @remarks     This method works only when the style of the %GroupedListView control is GROUPED_LIST_VIEW_STYLE_SECTION. @n
 863          *          If the device does not support the 32-bit color space, the method sets the alpha value of the specified color to @c 255.
 864          */
 865         result SetSectionColor(const Tizen::Graphics::Color& color);
 866
 867         /**
 868          * Gets the color of a section.
 869          *
 870          * @since       2.0
 871          *
 872          * @return      The section color, @n
 873          *                      else RGBA(0, 0, 0, 0) if the instance is invalid
 874          */
 875         Tizen::Graphics::Color GetSectionColor(void) const;
 876
 877         /**
 878          * Sets the color of a division line between items.
 879          *
 880          * @since       2.0
 881          *
 882          * @return      An error code
 883          * @param[in]   color                           The division line color
 884          * @exception   E_SUCCESS                       The method is successful.
 885          * @exception   E_SYSTEM                        A system error has occurred.
 886          */
 887         result SetItemDividerColor(const Tizen::Graphics::Color& color);
 888
 889         /**
 890          * Gets the color of a division line between items.
 891          *
 892          * @since       2.0
 893          *
 894          * @return  The color of a division line, @n
 895          *                      else RGBA(0, 0, 0, 0) if the instance is invalid
 896          */
 897         Tizen::Graphics::Color GetItemDividerColor(void) const;
 898
 899         /**
 900          * Sets the background color of this control.
 901          *
 902          * @since       2.0
 903          *
 904          * @return  An error code
 905          * @param[in]   color               The background color
 906          * @exception   E_SUCCESS                       The method is successful.
 907          * @remarks     If the device does not support the 32-bit color space, the method sets the alpha value of the specified color to @c 255. @n
 908          *                      The background bitmap has priority over the background color. When both the background bitmap and the background color are specified,
 909          *                      only the bitmap image is displayed.
 910          */
 911         result SetBackgroundColor(const Tizen::Graphics::Color& color);
 912
 913         /**
 914          * Gets the background color of this control.
 915          *
 916          * @since       2.0
 917          *
 918          * @return      The background color, @n
 919          *                      else RGBA(0, 0, 0, 0) if the instance is invalid
 920          */
 921         Tizen::Graphics::Color GetBackgroundColor(void) const;
 922
 923         /**
 924          * Sets the bitmap of this control.
 925          *
 926          * @since 2.0
 927          *
 928          * @return  An error code
 929          * @param[in] pBitmap           The bitmap for the list
 930          * @exception E_SUCCESS         The method is successful.
 931          * @exception E_SYSTEM          A system error has occurred.
 932          */
 933         result SetBackgroundBitmap(const Tizen::Graphics::Bitmap* pBitmap);
 934
 935         /**
 936          * Sets the bitmap of the empty list.
 937          *
 938          * @since       2.0
 939          *
 940          * @return      An error code
 941          * @param[in]   pBitmap                         The bitmap for the empty list
 942          * @exception   E_SUCCESS                       The method is successful.
 943          * @exception   E_SYSTEM                        A system error has occurred.
 944          */
 945         result SetBitmapOfEmptyList(const Tizen::Graphics::Bitmap* pBitmap);
 946
 947         /**
 948          * Sets the text of the empty list.
 949          *
 950          * @since       2.0
 951          *
 952          * @return      An error code
 953          * @param[in]   text                            The text for the empty list
 954          * @exception   E_SUCCESS                       The method is successful.
 955          * @exception   E_SYSTEM                        A system error has occurred.
 956          */
 957         result SetTextOfEmptyList(const Tizen::Base::String& text);
 958
 959         /**
 960          * Gets the text to display when there is no item in a list.
 961          *
 962          * @since       2.0
 963          *
 964          * @return      The text to be displayed, @n
 965          *                      else an empty string when the instance is invalid
 966          */
 967         Tizen::Base::String GetTextOfEmptyList(void) const;
 968
 969         /**
 970          * Sets the color of the text to be displayed when there is no item in a list.
 971          *
 972          * @since       2.0
 973          *
 974          * @return      An error code
 975          * @param[in]   color                           The color of the text to be displayed
 976          * @exception   E_SUCCESS                       The method is successful.
 977          * @exception   E_SYSTEM                        A system error has occurred.
 978          */
 979         result SetTextColorOfEmptyList(const Tizen::Graphics::Color& color);
 980
 981         /**
 982          * Gets the color of the text to be displayed when there is no item in a list.
 983          *
 984          * @since       2.0
 985          *
 986          * @return  The color of the text to be displayed, @n
 987          *                      else RGBA(0, 0, 0, 0) if the instance is invalid
 988          */
 989         Tizen::Graphics::Color GetTextColorOfEmptyList(void) const;
 990
 991         /**
 992          * Expands the group's items.
 993          *
 994          * @since 2.0
 995          *
 996          * @return An error code
 997          * @param[in] groupIndex The index of the group
 998          * @exception E_SUCCESS             The method is successful.
 999          * @exception E_OUT_OF_RANGE        A specified input parameter is invalid.
1000          * @exception E_SYSTEM              A system error has occurred.
1001          */
1002         result ExpandGroup(int groupIndex);
1003
1004         /**
1005          * Collapses the group's items.
1006          *
1007          * @since 2.0
1008          *
1009          * @return An error code
1010          * @param[in] groupIndex The index of the group
1011          * @exception E_SUCCESS         The method is successful.
1012          * @exception E_OUT_OF_RANGE    A specified input parameter is invalid.
1013          * @exception E_SYSTEM          A system error has occurred.
1014          */
1015         result CollapseGroup(int groupIndex);
1016
1017         /**
1018          * Checks whether the group is expanded.
1019          *
1020          * @since 2.0
1021          *
1022          * @return      @c true if the group is expanded, @n
1023          *                      @c else false
1024          *
1025          * @param[in] groupIndex The index of the group
1026          */
1027         bool IsGroupExpanded(int groupIndex) const;
1028
1029         /**
1030          * Begins the reordering mode.
1031          *
1032          * @since 2.0
1033          *
1034          * @return  An error code
1035          * @exception E_SUCCESS                         The method is successful.
1036          * @exception E_INVALID_OPERATION       The reordering mode is only supported when %GroupedListView% is constructed with GroupedListViewStyle::GROUPED_LIST_VIEW_STYLE_INDEXED style.
1037          * @see         GroupedListView::Construct()
1038          * @see         IGroupedListViewItemEventListener::OnGroupedListViewItemReordered()
1039          */
1040         result BeginReorderingMode(void);
1041
1042         /**
1043          * Ends the reordering mode.
1044          *
1045          * @since 2.0
1046          *
1047          * @return  An error code
1048          * @exception E_SUCCESS                         The method is successful.
1049          * @exception E_INVALID_OPERATION       The reordering mode is only supported when %GroupedListView% is constructed with GroupedListViewStyle::GROUPED_LIST_VIEW_STYLE_INDEXED style.
1050          * @see         GroupedListView::Construct()
1051          * @see         IGroupedListViewItemEventListener::OnGroupedListViewItemReordered()
1052          */
1053         result EndReorderingMode(void);
1054
1055         /**
1056          * Checks whether the %GroupedListView control is in reordering mode.
1057          *
1058          * @since 2.0
1059          *
1060          * @return      @c true if the %GroupedListView is in reordering mode,
1061          *                      else @c false
1062          */
1063         bool IsInReorderingMode(void) const;
1064
1065 protected:
1066         friend class _GroupedListViewImpl;
1067
1068 private:
1069         //
1070         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1071         //
1072         GroupedListView(const GroupedListView& rhs);
1073
1074         //
1075         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1076         //
1077         GroupedListView& operator =(const GroupedListView& rhs);
1078
1079 }; // GroupedListView
1080
1081 }}} // Tizen::Ui::Controls
1082
1083 #endif  // _FUI_CTRL_GROUPED_LIST_VIEW_H_