inc/FUiCtrlListView.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        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. @n 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.@n
 321          *                                                              The optimal size of the control is defined in
 322          *                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 323          * @param[in] itemDivider       Set to @c true to display an item divider, @n
 324          *                                                              else @c false
 325          * @param[in] fastScroll        Set to @c true to use fast scroll, @n
 326          *                              else @c false
 327          * @exception E_SUCCESS         The method is successful.
 328          * @exception E_INVALID_ARG     A specified input parameter is invalid. @n
 329          *                                                      Either the @c rect.width or @c rect.height parameter has a negative value.
 330          * @exception E_SYSTEM          A system error has occurred.
 331          * @endif
 332          */
 333         result Construct(const Tizen::Graphics::Rectangle& rect, bool itemDivider = true, bool fastScroll = false);
 334
 335         /**
 336          * Initializes this instance of %ListView with the specified parameters.
 337          *
 338          * @since 2.0
 339          *
 340          * @return  An error code
 341          * @param[in] rect              An instance of the Graphics::Rectangle class @n
 342          *                                                              This instance represents the x and y coordinates of the left top corner of the created %ListView along with the width
 343          *                                                              and height.@n
 344          *                                                              The optimal size of the control is defined in
 345          *                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 346          * @param[in] itemDivider       Set to @c true to display an item divider, @n
 347          *                                                              else @c false
 348          * @param[in] scrollStyle       Set to scroll style
 349          * @exception E_SUCCESS         The method is successful.
 350          * @exception E_INVALID_ARG     A specified input parameter is invalid. @n
 351          *                                                      Either the @c rect.width or @c rect.height parameter has a negative value.
 352          * @exception E_SYSTEM          A system error has occurred.
 353          */
 354         result Construct(const Tizen::Graphics::Rectangle& rect, bool itemDivider, ListScrollStyle scrollStyle);
 355
 356         /**
 357          * Initializes this instance of %ListView with the specified parameters.
 358          *
 359          * @since 2.1
 360          *
 361          * @return  An error code
 362          * @param[in] rect              An instance of the Graphics::Rectangle class @n
 363          *                                                              This instance represents the x and y coordinates of the left top corner of the created %ListView along with the width
 364          *                                                              and height.@n
 365          *                                                              The optimal size of the control is defined in
 366          *                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 367          * @param[in] itemDivider       Set to @c true to display an item divider, @n
 368          *                                                              else @c false
 369          * @param[in] scrollStyle       Set to scroll style
 370          * @exception E_SUCCESS         The method is successful.
 371          * @exception E_INVALID_ARG     A specified input parameter is invalid. @n
 372          *                                                      Either the @c rect.width or @c rect.height parameter has a negative value.
 373          * @exception E_SYSTEM          A system error has occurred.
 374          */
 375         result Construct(const Tizen::Graphics::FloatRectangle& rect, bool itemDivider, ListScrollStyle scrollStyle);
 376
 377         /**
 378          * Sets the item provider that creates and deletes items for the list.
 379          *
 380          * @since       2.0
 381          *
 382          * @return  An error code
 383          * @param[in] provider          The item provider to create and delete items
 384          * @exception E_SUCCESS         The method is successful.
 385          * @exception E_SYSTEM          A system error has occurred.
 386          * @remarks
 387          *                      - If an item provider is not set for the list, the list does not work.
 388          *                      - The specified @c provider should be allocated in heap memory.
 389          */
 390         result SetItemProvider(IListViewItemProvider& provider);
 391
 392         /**
 393          * Sets the item provider that creates and deletes items for the list.
 394          *
 395          * @since       2.1
 396          *
 397          * @return  An error code
 398          * @param[in] provider          The item provider to create and delete items
 399          * @exception E_SUCCESS         The method is successful.
 400          * @exception E_SYSTEM          A system error has occurred.
 401          * @remarks
 402          *                      - If an item provider is not set for the list, the list does not work.
 403          *                      - The specified @c provider should be allocated in heap memory.
 404          */
 405         result SetItemProvider(IListViewItemProviderF& provider);
 406
 407         /**
 408          * Adds a listener instance that listens to state changes of list view items. @n
 409          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 410          *
 411          * @since       2.0
 412          *
 413          * @param[in] listener              The event listener to add
 414          */
 415         void AddListViewItemEventListener(IListViewItemEventListener& listener);
 416
 417         /**
 418          * Removes a listener instance that listens to state changes of list view items. @n
 419          * The removed listener cannot listen to events when they are fired.
 420          *
 421          * @since       2.0
 422          *
 423          * @param[in] listener                  The event listener to remove
 424          */
 425         void RemoveListViewItemEventListener(IListViewItemEventListener& listener);
 426
 427         /**
 428          * Adds a listener instance that listens to state changes of a fast scroll. @n
 429          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 430          *
 431          * @since       2.0
 432          *
 433          * @param[in] listener                  The event listener to add
 434          */
 435         void AddFastScrollListener(IFastScrollListener& listener);
 436
 437         /**
 438          * Removes a listener instance that listens to state changes of a fast scroll. @n
 439          * The removed listener cannot listen to events when they are fired.
 440          *
 441          * @since       2.0
 442          *
 443          * @param[in] listener                  The event listener to remove
 444          */
 445         void RemoveFastScrollListener(IFastScrollListener& listener);
 446
 447         /**
 448          * Adds a listener instance that listens to state changes of a scroll event. @n
 449          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 450          *
 451          * @since       2.0
 452          *
 453          * @param[in] listener          The event listener to add
 454          * @see     IScrollEventListener::OnScrollEndReached()
 455          * @see     RemoveScrollEventListener()
 456          */
 457         void AddScrollEventListener(IScrollEventListener& listener);
 458
 459         /**
 460          * Adds a listener instance that listens to state changes of a scroll event. @n
 461          * The added listener can listen to events on a specified event dispatcher's context when they are fired.
 462          *
 463          * @since       2.1
 464          *
 465          * @param[in] listener          The event listener to add
 466          * @see     IScrollEventListener::OnScrollEndReached()
 467          * @see     RemoveScrollEventListener()
 468          */
 469         void AddScrollEventListener(IScrollEventListenerF& listener);
 470
 471         /**
 472          * Removes a listener instance that listens to state changes of a scroll event. @n
 473          * The removed listener cannot listen to events when they are fired.
 474          *
 475          * @since       2.0
 476          *
 477          * @param[in] listener                  The event listener to remove
 478          * @see         IScrollEventListener::OnScrollEndReached()
 479          * @see     AddScrollEventListener()
 480          */
 481         void RemoveScrollEventListener(IScrollEventListener& listener);
 482
 483         /**
 484          * Removes a listener instance that listens to state changes of a scroll event. @n
 485          * The removed listener cannot listen to events when they are fired.
 486          *
 487          * @since       2.1
 488          *
 489          * @param[in] listener                  The event listener to remove
 490          * @see         IScrollEventListener::OnScrollEndReached()
 491          * @see     AddScrollEventListener()
 492          */
 493         void RemoveScrollEventListener(IScrollEventListenerF& listener);
 494
 495         /**
 496          * Adds a link event listener.
 497          *
 498          * @since       2.0
 499          *
 500          * @param[in] listener          The event listener to add
 501          * @remarks  The added listener is notified when a link is selected by the user.
 502          * @see     RemoveUiLinkEventListener()
 503          */
 504         void AddUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
 505
 506         /**
 507          * Removes the specified link event listener. @n
 508          * The removed listener cannot listen to events when they are fired.
 509          *
 510          * @since       2.0
 511          *
 512          * @param[in] listener          The event listener to remove
 513          * @see     AddUiLinkEventListener()
 514          */
 515         void RemoveUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
 516
 517         /**
 518          * Sets the sweep event to enable.
 519          *
 520          * @since   2.0
 521          *
 522          * @return  An error code
 523          * @param[in] enable                    Set to @c true to enable the sweep, @n
 524          *                                                              else @c false
 525          * @exception E_SUCCESS         The method is successful.
 526          * @exception E_SYSTEM          A system error has occurred.
 527          */
 528         result SetSweepEnabled(bool enable);
 529
 530         /**
 531          * Sets the index list of the scroll by texts.
 532          *
 533          * @since       2.0
 534          *
 535          * @return  An error code
 536          * @param[in] text              The text of the index
 537          * @param[in] useSearchIcon             Set to @c true to show the magnifying icon, @n
 538          *                              else @c false
 539          * @exception E_SUCCESS         The method is successful.
 540          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 541          * @exception E_INVALID_STATE   This instance is in an invalid state.
 542          * @exception E_SYSTEM          A system error has occurred.
 543          */
 544         result SetFastScrollIndex(const Tizen::Base::String& text, bool useSearchIcon);
 545
 546         /**
 547          * Gets the index of the top drawn item of the %ListView control.
 548          *
 549          * @since       2.0
 550          *
 551          * @return  The index of the top drawn item
 552          */
 553         int GetTopDrawnItemIndex(void) const;
 554
 555         /**
 556          * Gets the index of the bottom drawn item of the %ListView control.
 557          *
 558          * @since       2.0
 559          *
 560          * @return  The index of the bottom drawn item
 561          */
 562         int GetBottomDrawnItemIndex(void) const;
 563
 564         /**
 565          * Scrolls to the item at the specified index. @n
 566          * The specified item is drawn at the top of the %ListView control.
 567          *
 568          * @since       2.0
 569          *
 570          * @return  An error code
 571          * @param[in] index                             The item index
 572          * @exception E_SUCCESS         The method is successful.
 573          * @exception E_OUT_OF_RANGE    The specified input parameter is invalid.
 574          * @exception E_SYSTEM          A system error has occurred.
 575          * @remarks     This method should be called only after list items are created. @n
 576          *                      If this method needs to be called early in the lifecycle of the ListView, then the UpdateList() method
 577          *                      should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 578          */
 579         result ScrollToItem(int index);
 580
 581         /**
 582          * Scrolls to the item at the specified index. @n
 583          * The specified item is drawn at the position specified by the item alignment.
 584          *
 585          * @since       2.0
 586          *
 587          * @return  An error code
 588          * @param[in] index             The item index
 589          * @param[in] itemAlignment             The item alignment
 590          * @exception E_SUCCESS         The method is successful.
 591          * @exception E_OUT_OF_RANGE    A specified input parameter is invalid.
 592          * @exception E_SYSTEM          A system error has occurred.
 593          */
 594         result ScrollToItem(int index, ListScrollItemAlignment itemAlignment);
 595
 596         /**
 597          * Sets the check status of the item at the specified index.
 598          *
 599          * @since       2.0
 600          *
 601          * @return  An error code
 602          * @param[in] index             The item index
 603          * @param[in] check                             The check status
 604          * @exception E_SUCCESS             The method is successful.
 605          * @exception E_OUT_OF_RANGE        A specified input parameter is invalid.
 606          * @exception E_INVALID_OPERATION   The item is disabled.
 607          * @exception E_SYSTEM              A system error has occurred.
 608          * @remarks  This method should be called only after list items are created. @n
 609          *                      If this method needs to be called early in the lifecycle of the ListView, then the UpdateList() method
 610          *                      should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 611          */
 612         result SetItemChecked(int index, bool check);
 613
 614         /**
 615          * Checks whether the item at the specified index is checked.
 616          *
 617          * @since       2.0
 618          *
 619          * @return  @c true if the item is checked, @n
 620          *          else @c false
 621          * @param[in] index                             The item index
 622          * @remarks  This method should be called only after list items are created. @n
 623          *                      If this method needs to be called early in the lifecycle of the ListView, then the UpdateList() method
 624          *                      should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 625          */
 626         bool IsItemChecked(int index) const;
 627
 628         /**
 629          * Sets the enabled/disabled status of the item at the specified index.
 630          *
 631          * @since       2.0
 632          *
 633          * @return      An error code
 634          * @param[in] index             The item index
 635          * @param[in] enable                    The enabled/disabled status
 636          * @exception E_SUCCESS         The method is successful.
 637          * @exception E_OUT_OF_RANGE    A specified input parameter is invalid.
 638          * @exception E_SYSTEM          A system error has occurred.
 639          * @remarks     This method should be called only after list items are created.  @n
 640          *                      If this method needs to be called early in the lifecycle of the ListView,
 641          *                      then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 642          *
 643          */
 644         result SetItemEnabled(int index, bool enable);
 645
 646         /**
 647          * Checks whether the item at the specified index is enabled.
 648          *
 649          * @since       2.0
 650          *
 651          * @return  @c true if the item is enabled, @n
 652          *          else @c false
 653          * @param[in] index                             The item index
 654          * @remarks This method should be called only after list items are created. @n
 655          *                      If this method needs to be called early in the lifecycle of the ListView, then the UpdateList() method
 656          *                      should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 657          */
 658         bool IsItemEnabled(int index) const;
 659
 660         /**
 661          * Counts the number of items.
 662          *
 663          * @since       2.0
 664          *
 665          * @return  The total number of items
 666          */
 667         int GetItemCount(void) const;
 668
 669         /**
 670          * Shows the description text of the given item.
 671          *
 672          * @since       2.0
 673          *
 674          * @return      An error code
 675          * @param[in] index                             The index of the item
 676          * @exception E_SUCCESS         The method is successful.
 677          * @exception E_OUT_OF_RANGE    The specified input parameter is invalid.
 678          * @exception E_SYSTEM          A system error has occurred.
 679          * @remarks
 680          *                      - If no description text is set to the item of the specified index, this method does not show the description text.
 681          *                      - This method should be called only after list items are created. @n
 682          *                      If this method needs to be called early in the lifecycle of the ListView, then the UpdateList() method
 683          *                      should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 684          */
 685         result ShowItemDescriptionText(int index);
 686
 687         /**
 688          * Hides the description text of the given item.
 689          *
 690          * @since       2.0
 691          *
 692          * @return  An error code
 693          * @param[in] index                             The index of the item
 694          * @exception E_SUCCESS         The method is successful.
 695          * @exception E_OUT_OF_RANGE    The specified input parameter is invalid.
 696          * @exception E_SYSTEM          A system error has occurred.
 697          * @remarks     This method should be called only after list items are created. @n
 698          *                      If this method needs to be called early in the lifecycle of the ListView, then the UpdateList() method
 699          *                      should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 700          */
 701         result HideItemDescriptionText(int index);
 702
 703         /**
 704          * Refreshes the specified item.
 705          *
 706          * @since       2.0
 707          *
 708          * @return  An error code
 709          * @param[in] index             The item index
 710          * @param[in] type              The item to add, remove, or modify
 711          * @exception E_SUCCESS            The method is successful.
 712          * @exception E_OUT_OF_RANGE       A specified input parameter is invalid.
 713          * @exception E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 714          * @exception E_SYSTEM             A system error has occurred.
 715          * @remarks
 716          *                      - 3 refresh types are supported:@c  LIST_REFRESH_TYPE_ITEM_ADD, @c LIST_REFRESH_TYPE_ITEM_REMOVE, and @c LIST_REFRESH_TYPE_ITEM_MODIFY. @n
 717          *                      @c LIST_REFRESH_TYPE_ITEM_ADD is used when new data is added to the data model. @n
 718          *                      @c LIST_REFRESH_TYPE_ITEM_REMOVE is used when a data is deleted from the data model. @n
 719          *                      @c LIST_REFRESH_TYPE_ITEM_MODIFY is used when an existing data has changes and needs to be updated. @n
 720          *                      Calling this method with @c LIST_REFRESH_TYPE_ITEM_MODIFY invokes the item provider to call DeleteItem() and CreateItem() for the given index in
 721          *                      sequence.
 722          *                      - This method should be called only after list items are created. @n
 723          *                      If this method needs to be called early in the lifecycle of the ListView, then the UpdateList() method
 724          *                      should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 725 This method internally calls Invalidate(), so you do not need to call them to update the screen.
 726          */
 727         result RefreshList(int index, ListRefreshType type);
 728
 729         /**
 730          * Refreshes the specified item's element.
 731          *
 732          * @since 2.0
 733          *
 734          * @return  An error code
 735          * @param[in] index             The item index
 736          * @param[in] elementId         The item element ID
 737          * @exception E_SUCCESS            The method is successful.
 738          * @exception E_OUT_OF_RANGE       A specified input parameter is invalid.
 739          * @exception E_SYSTEM             A system error has occurred.
 740          * @remarks  This method internally calls Invalidate(), so you do not need to call them to update the screen.
 741          */
 742         result RefreshList(int index, int elementId);
 743
 744         /**
 745          * Updates the whole items of a list.
 746          *
 747          * @since       2.0
 748          *
 749          * @return  An error code
 750          * @exception E_SUCCESS         The method is successful.
 751          * @exception E_SYSTEM          A system error has occurred.
 752          * @remarks     This method clears the items in the list and re-invokes the methods of the item provider to fill the list.
 753          */
 754         result UpdateList(void);
 755
 756         /**
 757          * Gets the index of the item at the specified position.
 758          *
 759          * @since       2.0
 760          *
 761          * @return  The index of the item, @n
 762          *                      else @c -1 if there is no list item at the specified position
 763          * @param[in] x                                 The X position of the point
 764          * @param[in] y                 The Y position of the point
 765          * @remarks
 766          *                      - The method returns @c -1 when there is no list item at the specified position.
 767          *                      - This method should be called only after list items are created. @n
 768          *                      If this method needs to be called early in the lifecycle of the ListView, then the UpdateList() method
 769          *                      should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 770          *
 771          */
 772         int GetItemIndexFromPosition(int x, int y) const;
 773
 774         /**
 775          * Gets the index of the item at a specified position.
 776          *
 777          * @since       2.1
 778          *
 779          * @return  The index of the item, @n
 780          *                      else @c -1 if there is no list item at the specified position
 781          * @param[in] x                                 The X position of the point
 782          * @param[in] y                 The Y position of the point
 783          * @remarks
 784          *                      - This method returns @c -1 when there is no list item at the specified position.
 785          *                      - This method should be called only after list items are created. @n If this method needs to
 786          *                      be called early in the lifecycle of the ListView, then the UpdateList() method should be called explicitly
 787          *                      (for example, during Tizen::Ui::Control::OnInitializing()).
 788          */
 789         int GetItemIndexFromPosition(float x, float y) const;
 790
 791         /**
 792          * Gets the index of the item at the specified position.
 793          *
 794          * @since       2.0
 795          *
 796          * @return  The index of the item
 797          * @param[in] position          The position of the point, @n
 798          *                                                      else @c -1 if there is no list item at the specified position
 799          * @remarks This method should be called only after list items are created. @n If this method needs to
 800          *                      be called early in the lifecycle of the ListView, then the UpdateList() method should be called
 801          *                      explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 802          */
 803         int GetItemIndexFromPosition(const Tizen::Graphics::Point& position) const;
 804
 805         /**
 806          * Gets the index of the item at a specified position.
 807          *
 808          * @since       2.1
 809          *
 810          * @return  The index of the item
 811          * @param[in] position          The position of the point, @n
 812          *                                                      else @c -1 if there is no list item at the specified position
 813          * @remarks This method should be called only after list items are created. @n
 814          *                      If this method needs to be called early in the lifecycle of the ListView, then the UpdateList() method
 815          *                      should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 816          */
 817         int GetItemIndexFromPosition(const Tizen::Graphics::FloatPoint& position) 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] x                 The X position of the item
 826          * @param[in] y                 The Y position of the item
 827          * @param[out] itemIndex                The index of the item
 828          * @param[out] elementId        The ID of the element
 829          * @exception E_SUCCESS         The method is successful.
 830          * @exception E_SYSTEM          A system error has occurred, or @n
 831          *                                                              there is no item at the specified position.
 832          * @remarks
 833          *                      - The specified @c itemIndex is -1 when there is no list item at the specified position.
 834          *                      - The specified @c elementId is -1 when there is no element at the specified position.
 835          *                      - This method should be called only after list items are created.  @n
 836          *                      If this method needs to be called early in the lifecycle of the ListView,
 837          *                      then the UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 838          */
 839         result GetItemIndexFromPosition(int x, int y, int& itemIndex, int& elementId) const;
 840
 841         /**
 842          * Gets the index of the item and ID of the element at a specified position.
 843          *
 844          * @since       2.1
 845          *
 846          * @return  An error code
 847          * @param[in] x                 The X position of the item
 848          * @param[in] y                 The Y position of the item
 849          * @param[out] itemIndex                The index of the item
 850          * @param[out] elementId        The ID of the element
 851          * @exception E_SUCCESS         The method is successful.
 852          * @exception E_SYSTEM          A system error has occurred, or @n
 853          *                                                              there is no item at the specified position.
 854          * @remarks
 855          *                      - The specified @c itemIndex is @c -1 when there is no list item at the specified position.
 856          *                      - The specified @c elementId is @c -1 when there is no element at the specified position.
 857          *                      - This method should be called only after list items are created. @n
 858          *                      If this method needs to be called early in the lifecycle of the ListView,
 859          *                      then the UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 860          */
 861         result GetItemIndexFromPosition(float x, float y, int& itemIndex, int& elementId) const;
 862
 863         /**
 864          * Gets the index of the item and ID of the element at the specified position.
 865          *
 866          * @since       2.0
 867          *
 868          * @return  An error code
 869          * @param[in] position          The position of the point
 870          * @param[out] itemIndex        The index of the item
 871          * @param[out] elementId                The ID of the element
 872          * @exception E_SUCCESS         The method is successful.
 873          * @exception E_SYSTEM          A system error has occurred, or @n
 874          *                                                              there is no item at the specified position.
 875          * @remarks
 876          *                      - The specified @c itemIndex is -1 when there is no list item at the specified position.
 877          *                      -  The specified @c elementId is -1 when there is no element at the specified position.
 878          *                      - This method should be called only after list items are created. @n
 879          *                      If this method needs to be called early in the lifecycle of the ListView,
 880          *                      then the UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 881          */
 882         result GetItemIndexFromPosition(const Tizen::Graphics::Point& position, int& itemIndex, int& elementId) const;
 883
 884         /**
 885          * Gets the index of the item and ID of the element at a specified position.
 886          *
 887          * @since       2.1
 888          *
 889          * @return  An error code
 890          * @param[in] position          The position of the point
 891          * @param[out] itemIndex        The index of the item
 892          * @param[out] elementId                The ID of the element
 893          * @exception E_SUCCESS         The method is successful.
 894          * @exception E_SYSTEM          A system error has occurred, or @n
 895          *                                                              there is no item at the specified position.
 896          * @remarks
 897          *                      - The specified @c itemIndex is @c -1 when there is no list item at the specified position.
 898          *                      - The specified @c elementId is @c -1 when there is no element at the specified position.
 899          *                      - This method should be called only after list items are created. @n
 900          *                      If this method needs to be called early in the lifecycle of the ListView,
 901          *                      then the UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
 902          */
 903         result GetItemIndexFromPosition(const Tizen::Graphics::FloatPoint& position, int& itemIndex, int& elementId) const;
 904
 905         /**
 906          * Sets the color of a division line between items.
 907          *
 908          * @since       2.0
 909          *
 910          * @return  An error code
 911          * @param[in] color                             The division line color
 912          * @exception E_SUCCESS         The method is successful.
 913          */
 914         result SetItemDividerColor(const Tizen::Graphics::Color& color);
 915
 916         /**
 917          * Gets the color of a division line between items.
 918          *
 919          * @since       2.0
 920          *
 921          * @return  The color of a section, @n
 922          *                      else RGBA(0, 0, 0, 0) if the instance is invalid
 923          */
 924         Tizen::Graphics::Color GetItemDividerColor(void) const;
 925
 926         /**
 927          * Sets the background color of this control.
 928          *
 929          * @since       2.0
 930          *
 931          * @return  An error code
 932          * @param[in] color                             The background color
 933          * @exception E_SUCCESS                 The method is successful.
 934          * @remarks
 935          *                      - The method sets the alpha value of the specified @c color to @c 255, when a device does not support 32bit color space.
 936          *                      - The background bitmap has priority over the background color. When both the background bitmap and the background color are specified, only
 937          *                      the bitmap image is displayed.
 938          */
 939         result SetBackgroundColor(const Tizen::Graphics::Color& color);
 940
 941         /**
 942          * Gets the background color of this control.
 943          *
 944          * @since       2.0
 945          *
 946          * @return      The background color, @n
 947          *                      else RGBA(0, 0, 0, 0) if the instance is invalid
 948          */
 949         Tizen::Graphics::Color GetBackgroundColor(void) const;
 950
 951         /**
 952          * Sets the bitmap of this control.
 953          *
 954          * @since 2.0
 955          *
 956          * @return  An error code
 957          * @param[in] pBitmap           The bitmap for the list
 958          * @exception E_SUCCESS         The method is successful.
 959          * @exception E_SYSTEM          A system error has occurred.
 960          */
 961         result SetBackgroundBitmap(const Tizen::Graphics::Bitmap* pBitmap);
 962
 963         /**
 964          * Sets the bitmap of the empty list.
 965          *
 966          * @since   2.0
 967          *
 968          * @return  An error code
 969          * @param[in] pBitmap           The bitmap for the empty list
 970          * @exception E_SUCCESS         The method is successful.
 971          * @exception E_SYSTEM          A system error has occurred.
 972          */
 973         result SetBitmapOfEmptyList(const Tizen::Graphics::Bitmap* pBitmap);
 974
 975         /**
 976          * Sets the text of the empty list.
 977          *
 978          * @since    2.0
 979          *
 980          * @return   An error code
 981          * @param[in] text              The text for the empty list
 982          * @exception E_SUCCESS         The method is successful.
 983          * @exception E_SYSTEM          A system error has occurred.
 984          */
 985         result SetTextOfEmptyList(const Tizen::Base::String& text);
 986
 987         /**
 988          * Gets the text to display when there is no item in a list.
 989          *
 990          * @since       2.0
 991          *
 992          * @return      The text to display, @n
 993          *                      else an empty string if the instance is invalid
 994          */
 995         Tizen::Base::String GetTextOfEmptyList(void) const;
 996
 997         /**
 998          * Sets a color of the text to display when there is no item in a list.
 999          *
1000          * @since       2.0
1001          *
1002          * @return  An error code
1003          * @param[in] color             The color of the text to display
1004          * @exception E_SUCCESS         The method is successful.
1005          * @exception E_SYSTEM          A system error has occurred.
1006          */
1007         result SetTextColorOfEmptyList(const Tizen::Graphics::Color& color);
1008
1009         /**
1010          * Gets a color of the text to display when there is no item in a list.
1011          *
1012          * @since       2.0
1013          *
1014          * @return  The color of the text to display
1015          */
1016         Tizen::Graphics::Color GetTextColorOfEmptyList(void) const;
1017
1018         /**
1019          * Begins the reordering mode.
1020          *
1021          * @since 2.0
1022          *
1023          * @return  An error code
1024          * @exception E_SUCCESS         The method is successful.
1025          * @exception E_SYSTEM          A system error has occurred.
1026          * @see    IListViewItemEventListener::OnListViewItemReordered()
1027          */
1028         result BeginReorderingMode(void);
1029
1030         /**
1031          * Ends the reordering mode.
1032          *
1033          * @since 2.0
1034          *
1035          * @return  An error code
1036          * @exception E_SUCCESS         The method is successful.
1037          * @exception E_SYSTEM          A system error has occurred.
1038          * @see    IListViewItemEventListener::OnListViewItemReordered()
1039          */
1040         result EndReorderingMode(void);
1041
1042         /**
1043          * Checks whether the %ListView control is in reordering mode.
1044          *
1045          * @since 2.0
1046          *
1047          * @return      @c true if the %ListView is in reordering mode, @n
1048          *              else @c false
1049          */
1050         bool IsInReorderingMode(void) const;
1051
1052         /**
1053          * Sets the scroll input handling mode.
1054          *
1055          * @since 2.1
1056          *
1057          * @param[in] mode  The scroll input handling mode
1058          * @see             GetScrollInputMode()
1059          */
1060         void SetScrollInputMode(ScrollInputMode mode);
1061
1062
1063         /**
1064          * Gets the scroll input handling mode.
1065          *
1066          * @since 2.1
1067          *
1068          * @return     The scroll input handling mode
1069          * @see        SetScrollInputMode()
1070          */
1071         ScrollInputMode GetScrollInputMode(void) const;
1072
1073         /**
1074          * Opens the context item at a specified index.
1075          *
1076          * @since 2.1
1077          *
1078          * @return  An error code
1079          * @param[in] itemIndex         The item index
1080          * @exception E_SUCCESS                         The method is successful.
1081          * @exception E_OUT_OF_RANGE            The specified input parameter is invalid.
1082          * @exception E_INVALID_OPERATION       The current state of the instance prohibits the execution of the specified operation.
1083          */
1084         result OpenContextItem(int itemIndex);
1085
1086         /**
1087          * Closes the context item at a specified index.
1088          *
1089          * @since 2.1
1090          *
1091          * @return  An error code
1092          * @param[in] itemIndex         The item index
1093          * @exception E_SUCCESS                         The method is successful.
1094          * @exception E_OUT_OF_RANGE                    The specified input parameter is invalid.
1095          * @exception E_INVALID_OPERATION       The current state of the instance prohibits the execution of the specified operation.
1096          */
1097         result CloseContextItem(int itemIndex);
1098
1099         /**
1100          * Checks whether the context item at a specified index is opened.
1101          *
1102          * @since 2.1
1103          *
1104          * @return      @c true if the context item is opened, @n
1105          *                      else @c false
1106          * @param[in] itemIndex         The item index
1107          * @exception E_SUCCESS                 The method is successful.
1108          * @exception E_OUT_OF_RANGE    The specified input parameter is invalid.
1109          */
1110         bool IsContextItemOpened(int itemIndex) const;
1111
1112 protected:
1113         friend class _ListViewImpl;
1114
1115 private:
1116         //
1117         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1118         //
1119         ListView(const ListView& rhs);
1120
1121         //
1122         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1123         //
1124         ListView& operator =(const ListView& rhs);
1125 }; // ListView
1126
1127 }}} // Tizen::Ui::Controls
1128
1129 #endif  // _FUI_CTRL_LIST_VIEW_H_