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