inc/FUiCtrlIconListView.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        FUiCtrlIconListView.h
  20  * @brief       This is the header file for the %IconListView class.
  21  *
  22  * This header file contains the declarations of the %IconListView class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_ICON_LIST_VIEW_H_
  26 #define _FUI_CTRL_ICON_LIST_VIEW_H_
  27
  28 //Includes
  29 #include <FGrpFloatRectangle.h>
  30 #include <FOspConfig.h>
  31 #include <FUiContainer.h>
  32 #include <FUiCtrlControlsTypes.h>
  33 #include <FUiCtrlIconListViewTypes.h>
  34 #include <FUiCtrlIIconListViewItemEventListener.h>
  35 #include <FUiCtrlIIconListViewItemProvider.h>
  36 #include <FUiCtrlIScrollEventListener.h>
  37 #include <FUiCtrlIScrollEventListenerF.h>
  38 #include <FUiCtrlListViewTypes.h>
  39 #include <FUiCtrlScrollPanelTypes.h>
  40
  41 namespace Tizen { namespace Ui { namespace Controls
  42 {
  43
  44 /**
  45  * @class       IconListView
  46  * @brief   This class defines the common behavior for a %IconListView control.
  47  *
  48  * @since       2.0
  49  *
  50  * The %IconListView class displays a 2-dimentional list of bitmap images and icons.
  51  *
  52  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_listviews.htm">ListViews</a>.
  53  *
  54  * The following example demonstrates how to use the %IconListView class.
  55  *
  56  * @code
  57 //Sample code for IconListViewSample.h
  58 #include <FUi.h>
  59
  60 class IconListViewSample
  61         : public Tizen::Ui::Controls::Form
  62         , public Tizen::Ui::Controls::IIconListViewItemProvider
  63         , public Tizen::Ui::Controls::IIconListViewItemEventListener
  64 {
  65 public:
  66         IconListViewSample(void)
  67         : __pIconListView(null){}
  68
  69         bool Initialize(void);
  70         virtual result OnInitializing(void);
  71         virtual result OnTerminating(void);
  72
  73         // IIconListViewItemEventListener
  74         virtual void OnIconListViewItemStateChanged(Tizen::Ui::Controls::IconListView &view, int index, Tizen::Ui::Controls::IconListViewItemStatus status);
  75
  76         //IIconListViewItemProvider
  77         virtual Tizen::Ui::Controls::IconListViewItem* CreateItem(int index);
  78         virtual bool DeleteItem(int index, Tizen::Ui::Controls::IconListViewItem* pItem);
  79         virtual int GetItemCount(void);
  80
  81 private:
  82         Tizen::Graphics::Bitmap* __pHome;
  83         Tizen::Graphics::Bitmap* __pMsg;
  84         Tizen::Graphics::Bitmap* __pAlarm;
  85
  86         Tizen::Ui::Controls::IconListView* __pIconListView;
  87 };
  88  *      @endcode
  89  *
  90  *      @code
  91 //Sample code for IconListViewSample.cpp
  92 #include <FApp.h>
  93 #include <FGraphics.h>
  94
  95 #include "IconListViewSample.h"
  96
  97 using namespace Tizen::App;
  98 using namespace Tizen::Base;
  99 using namespace Tizen::Graphics;
 100 using namespace Tizen::Ui;
 101 using namespace Tizen::Ui::Controls;
 102
 103 bool
 104 IconListViewSample::Initialize(void)
 105 {
 106         Construct(FORM_STYLE_NORMAL);
 107         return true;
 108 }
 109
 110 result
 111 IconListViewSample::OnInitializing(void)
 112 {
 113         result r = E_SUCCESS;
 114
 115         // Creates an instance of IconListView
 116         __pIconListView = new IconListView();
 117         __pIconListView->Construct(Rectangle(0, 0, GetClientAreaBounds().width, GetClientAreaBounds().height),
 118                         Dimension(100, 100), ICON_LIST_VIEW_STYLE_NORMAL, ICON_LIST_VIEW_SCROLL_DIRECTION_VERTICAL);
 119         __pIconListView->SetItemProvider(*this);
 120         __pIconListView->AddIconListViewItemEventListener(*this);
 121
 122         // Adds the icon list view to the form
 123         AddControl(*__pIconListView);
 124
 125         // Gets instances of Bitmap
 126         AppResource* pAppResource = Application::GetInstance()->GetAppResource();
 127         __pHome  = pAppResource->GetBitmapN(L"home.png");
 128         __pMsg = pAppResource->GetBitmapN(L"message.png");
 129         __pAlarm  = pAppResource->GetBitmapN(L"alarm.png");
 130
 131         return r;
 132 }
 133
 134 result
 135 IconListViewSample::OnTerminating(void)
 136 {
 137         result r = E_SUCCESS;
 138
 139         // Deallocates bitmaps
 140         delete __pHome;
 141         delete __pMsg;
 142         delete __pAlarm;
 143
 144         return r;
 145 }
 146
 147 int
 148 IconListViewSample::GetItemCount(void)
 149 {
 150         return 3;
 151 }
 152
 153 IconListViewItem*
 154 IconListViewSample::CreateItem(int index)
 155 {
 156         // Creates an instance of IconListViewItem
 157         IconListViewItem* pIconListview = new IconListViewItem();
 158
 159         // Creates an instance of String
 160         String* pStr = new String();
 161
 162         switch (index % 3)
 163         {
 164         case 0:
 165                 {
 166                         *pStr = L"Home";
 167                         pIconListview->Construct(*__pHome, pStr);
 168                 }
 169                 break;
 170         case 1:
 171                 {
 172                         *pStr = L"Msg";
 173                         pIconListview->Construct(*__pMsg, pStr);
 174                 }
 175                 break;
 176         case 2:
 177                 {
 178                         *pStr = L"Alarm";
 179                         pIconListview->Construct(*__pAlarm, pStr);
 180                 }
 181                 break;
 182         }
 183
 184         // Deallocates the string
 185         delete pStr;
 186
 187         return pIconListview;
 188 }
 189
 190 bool
 191 IconListViewSample::DeleteItem(int index, IconListViewItem* pItem)
 192 {
 193         delete pItem;
 194         return true;
 195 }
 196
 197 void
 198 IconListViewSample::OnIconListViewItemStateChanged (IconListView &view, int index, IconListViewItemStatus status)
 199 {
 200         switch (index)
 201         {
 202         case 0:
 203                 {
 204                         // ....
 205                 }
 206                 break;
 207         case 1:
 208                 {
 209                         // ....
 210                 }
 211                 break;
 212         default:
 213                 break;
 214         }
 215 }
 216  * @endcode
 217  *
 218  */
 219 class _OSP_EXPORT_ IconListView
 220         : public Tizen::Ui::Control
 221 {
 222 public:
 223         /**
 224          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 225          *
 226          * @since       2.0
 227          */
 228         IconListView(void);
 229
 230         /**
 231          * This destructor overrides Tizen::Base::Object::~Object().
 232          *
 233          * @since       2.0
 234          */
 235         virtual ~IconListView(void);
 236
 237 public:
 238         /**
 239          * Initializes this instance of %IconListView with the specified parameters.
 240          *
 241          * @since 2.0
 242          *
 243          * @return      An error code
 244          * @param[in]   rect                            An instance of the Graphics::Rectangle class @n
 245          *                                                                      This instance represents the x and y coordinates of the top-left corner of the created %IconListView along with the width and height.
 246          * @param[in]   itemBitmapSize          The size of an icon in the %IconListView
 247          * @param[in]   style                           The style set of %IconListView
 248          * @param[in]   direction                       The direction of scroll
 249          * @param[in]   scrollStyle                     The scroll style of %IconListView
 250          * @exception   E_SUCCESS                       The method is successful.
 251          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 252          * @exception   E_SYSTEM                        A system error has occurred.
 253          * @remarks     A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
 254          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and margins. @n
 255          *                      The %IconListView cannot display more than 256 items on the screen at once.
 256          * @remarks     The actual size of bitmap to be displayed in %IconListView is smaller than the specified size when the border style is ICON_LIST_VIEW_ITEM_BORDER_STYLE_SHADOW.
 257          */
 258         result Construct(const Tizen::Graphics::Rectangle& rect, const Tizen::Graphics::Dimension& itemBitmapSize, IconListViewStyle style = ICON_LIST_VIEW_STYLE_NORMAL, IconListViewScrollDirection direction = ICON_LIST_VIEW_SCROLL_DIRECTION_VERTICAL, IconListViewScrollStyle scrollStyle = ICON_LIST_SCROLL_STYLE_FADE_OUT);
 259
 260         /**
 261          * Initializes this instance of %IconListView with the specified parameters.
 262          *
 263          * @since 2.1
 264          *
 265          * @return      An error code
 266          * @param[in]   rect                            An instance of the Graphics::FloatRectangle class @n
 267          *                                                                      This instance represents the x and y coordinates of the top-left corner of the created %IconListView along with the width and height.
 268          * @param[in]   itemBitmapSize          The size of an icon in the %IconListView
 269          * @param[in]   style                           The style set of %IconListView
 270          * @param[in]   direction                       The direction of scroll
 271          * @param[in]   scrollStyle                     The scroll style of %IconListView
 272          * @exception   E_SUCCESS                       The method is successful.
 273          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 274          * @exception   E_SYSTEM                        A system error has occurred.
 275          * @remarks     A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
 276          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and margins. @n
 277          *                      The %IconListView cannot display more than 256 items on the screen at once.
 278          * @remarks     The actual size of bitmap to be displayed in %IconListView is smaller than the specified size when the border style is ICON_LIST_VIEW_ITEM_BORDER_STYLE_SHADOW.
 279          */
 280         result Construct(const Tizen::Graphics::FloatRectangle& rect, const Tizen::Graphics::FloatDimension& itemBitmapSize, IconListViewStyle style = ICON_LIST_VIEW_STYLE_NORMAL, IconListViewScrollDirection direction = ICON_LIST_VIEW_SCROLL_DIRECTION_VERTICAL, IconListViewScrollStyle scrollStyle = ICON_LIST_SCROLL_STYLE_FADE_OUT);
 281
 282         /**
 283          * Sets the item provider that creates and deletes items for the %IconListView control.
 284          *
 285          * @since   2.0
 286          *
 287          * @return      An error code
 288          * @param[in]   provider                        The item provider to create and delete items
 289          * @exception   E_SUCCESS                       The method is successful.
 290          * @exception   E_SYSTEM                        A system error has occurred.
 291          * @remarks     If an item provider is not set for the %IconListView, it does not work. @n
 292          *                      The specified @c provider should be allocated in heap memory.
 293          */
 294         result SetItemProvider(IIconListViewItemProvider& provider);
 295
 296         /**
 297          * Adds a listener instance. @n
 298          * The added listener can listen to item events when they are fired.
 299          *
 300          * @since   2.0
 301          *
 302          * @param[in]   listener                        The listener to be added
 303          */
 304         void AddIconListViewItemEventListener(IIconListViewItemEventListener& listener);
 305
 306         /**
 307          * Removes a listener instance. @n
 308          * The removed listener cannot listen to events when they are fired.
 309          *
 310          * @since   2.0
 311          *
 312          * @param[in]   listener                        The listener to be removed
 313          */
 314         void RemoveIconListViewItemEventListener(IIconListViewItemEventListener& listener);
 315
 316         /**
 317          * Adds a listener instance that listens to state changes of a scroll event. @n
 318          * The added listener can listen to events on the context of the given event dispatcher when they are fired.
 319          *
 320          * @since   2.0
 321          *
 322          * @param[in]   listener                        The event listener to be added
 323          * @see                 IScrollEventListener::OnScrollEndReached()
 324          * @see                 RemoveScrollEventListener()
 325          */
 326         void AddScrollEventListener(IScrollEventListener& listener);
 327
 328         /**
 329          * Adds a listener instance that listens to state changes of a scroll event. @n
 330          * The added listener can listen to events on the context of the given event dispatcher when they are fired.
 331          *
 332          * @since   2.1
 333          *
 334          * @param[in]   listener                        The event listener to be added
 335          * @see                 IScrollEventListenerF::OnScrollEndReached()
 336          * @see                 RemoveScrollEventListener()
 337          */
 338         void AddScrollEventListener(IScrollEventListenerF& listener);
 339
 340         /**
 341          * Removes a listener instance that listens to state changes of a scroll event. @n
 342          * The removed listener cannot listen to events when they are fired.
 343          *
 344          * @since   2.0
 345          *
 346          * @param[in]   listener                        The event listener to be removed
 347          * @see                 IScrollEventListener::OnScrollEndReached()
 348          * @see                 RemoveScrollEventListener()
 349          */
 350         void RemoveScrollEventListener(IScrollEventListener& listener);
 351
 352         /**
 353          * Removes a listener instance that listens to state changes of a scroll event. @n
 354          * The removed listener cannot listen to events when they are fired.
 355          *
 356          * @since   2.1
 357          *
 358          * @param[in]   listener                        The event listener to be removed
 359          * @see                 IScrollEventListenerF::OnScrollEndReached()
 360          * @see                 RemoveScrollEventListener()
 361          */
 362         void RemoveScrollEventListener(IScrollEventListenerF& listener);
 363
 364         /**
 365          * Sets the background bitmap of the %IconListView.
 366          *
 367          * @since   2.0
 368          *
 369          * @param[in]   pBitmap                         The background bitmap
 370          * @exception   E_SUCCESS                       The method is successful.
 371          * @exception   E_SYSTEM                        A system error has occurred.
 372          * @remarks     When @c pBitmap is null, %IconListView does not have a background bitmap. The default value for the background bitmap is @c null.
 373          * @remarks     The background bitmap has priority over the background color. When both the background bitmap and the background color are specified,
 374          *                      only the bitmap is displayed.
 375          */
 376         result SetBackgroundBitmap(const Tizen::Graphics::Bitmap* pBitmap);
 377
 378         /**
 379          * Sets the background color of this control.
 380          *
 381          * @since   2.0
 382          *
 383          * @return      An error code
 384          * @param[in]   color               The background color
 385          * @exception   E_SUCCESS                       The method is successful.
 386          * @remarks     The method sets the alpha value of the specified color to 255, when a device does not support 32 bit color space.
 387          * @remarks     The background bitmap has priority over the background color. When both the background bitmap and the background color are specified,
 388          *                      only the bitmap is displayed.
 389          */
 390         result SetBackgroundColor(const Tizen::Graphics::Color& color);
 391
 392         /**
 393          * Gets the background color of this control.
 394          *
 395          * @since       2.0
 396          *
 397          * @return      The background color, @n
 398          *                      else RGBA(0, 0, 0, 0) if an error occurs
 399          */
 400         Tizen::Graphics::Color GetBackgroundColor(void) const;
 401
 402         /**
 403          * Sets the margin of %IconListView.
 404          *
 405          * @since   2.0
 406          *
 407          * @return      An error code
 408          * @param[in]   type                            The type of margin
 409          * @param[in]   value                           The marginal value
 410          * @exception   E_SUCCESS                       The method is successful.
 411          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 412          * @exception   E_SYSTEM                        A system error has occurred.
 413          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and
 414          *                      margins. The %IconListView cannot display more than 256 items on screen at once.
 415          */
 416         result SetMargin(MarginType type, int value);
 417
 418         /**
 419          * Sets the margin of %IconListView.
 420          *
 421          * @since   2.1
 422          *
 423          * @return      An error code
 424          * @param[in]   type                            The type of margin
 425          * @param[in]   value                           The marginal value
 426          * @exception   E_SUCCESS                       The method is successful.
 427          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 428          * @exception   E_SYSTEM                        A system error has occurred.
 429          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and
 430          *                      margins. The %IconListView cannot display more than 256 items on screen at once.
 431          */
 432         result SetMargin(MarginType type, float value);
 433
 434         /**
 435          * Gets the margin of %IconListView.
 436          *
 437          * @since   2.0
 438          *
 439          * @return      The marginal value of %IconListView, @n
 440          *                      else @c -1 if an error occurs
 441          * @param[in]   type                            The type of margin
 442          */
 443         int GetMargin(MarginType type) const;
 444
 445         /**
 446          * Gets the margin of %IconListView.
 447          *
 448          * @since   2.1
 449          *
 450          * @return      The marginal value of %IconListView, @n
 451          *                      else @c -1 if an error occurs
 452          * @param[in]   type                            The type of margin
 453          */
 454         float GetMarginF(MarginType type) const;
 455
 456         /**
 457          * Sets the horizontal and vertical spacing between the items.
 458          *
 459          * @since   2.0
 460          *
 461          * @return      An error code
 462          * @param[in]   horizontalSpacing       The spacing between items in horizontal direction
 463          * @param[in]   verticalSpacing         The spacing between items in vertical direction
 464          * @exception   E_SUCCESS                       The method is successful.
 465          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 466          * @exception   E_SYSTEM                        A system error has occurred.
 467          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and
 468          *                      margins. The %IconListView cannot display more than 256 items on screen at once.
 469          */
 470         result SetItemSpacing(int horizontalSpacing, int verticalSpacing);
 471
 472         /**
 473          * Sets the horizontal and vertical spacing between the items.
 474          *
 475          * @since   2.1
 476          *
 477          * @return      An error code
 478          * @param[in]   horizontalSpacing       The spacing between items in horizontal direction
 479          * @param[in]   verticalSpacing         The spacing between items in vertical direction
 480          * @exception   E_SUCCESS                       The method is successful.
 481          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 482          * @exception   E_SYSTEM                        A system error has occurred.
 483          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and
 484          *                      margins. The %IconListView cannot display more than 256 items on screen at once.
 485          */
 486         result SetItemSpacing(float horizontalSpacing, float verticalSpacing);
 487
 488         /**
 489          * Gets the horizontal spacing between items of %IconListView.
 490          *
 491          * @since   2.0
 492          *
 493          * @return      The value of space between items in horizontal direction, @n
 494          *                      else @c -1 if an error occurs
 495          */
 496         int GetItemHorizontalSpacing(void) const;
 497
 498         /**
 499          * Gets the horizontal spacing between items of %IconListView.
 500          *
 501          * @since   2.1
 502          *
 503          * @return      The value of space between items in horizontal direction, @n
 504          *                      else @c -1 if an error occurs
 505          */
 506         float GetItemHorizontalSpacingF(void) const;
 507
 508         /**
 509          * Gets the vertical spacing between items of %IconListView.
 510          *
 511          * @since   2.0
 512          *
 513          * @return      The value of space between items in vertical direction, @n
 514          *                      else @c -1 if an error occurs
 515          */
 516         int GetItemVerticalSpacing(void) const;
 517
 518         /**
 519          * Gets the vertical spacing between items of %IconListView.
 520          *
 521          * @since   2.1
 522          *
 523          * @return      The value of space between items in vertical direction, @n
 524          *                      else @c -1 if an error occurs
 525          */
 526         float GetItemVerticalSpacingF(void) const;
 527
 528         /**
 529          * Sets the checked status of the specified item of %IconListView.
 530          *
 531          * @since   2.0
 532          *
 533          * @return      An error code
 534          * @param[in]   index                           The index of the %IconListView item
 535          * @param[in]   check                           The check status
 536          * @exception   E_SUCCESS                       The method is successful.
 537          * @exception   E_SYSTEM                        A system error has occurred.
 538          * @exception   E_OUT_OF_RANGE          The specified @c index is out of range.
 539          * @remarks     This method can only be used when the style of the list allows selection.
 540          * @remarks     The method only changes the state of the list item. %IconListView needs to be redrawn to reflect the change on the screen.
 541          * @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 IconListView, then UpdateList() method should be called explicitly (e.g. during Tizen::Ui::Control::OnInitializing()).
 542          */
 543         result SetItemChecked(int index, bool check);
 544
 545         /**
 546          * Checks whether the specified item is checked.
 547          *
 548          * @since   2.0
 549          *
 550          * @return      @c true if the specified item is checked, @n
 551          *                      else @c false
 552          * @param[in]   index                           The index of the item
 553          * @remarks  This method can only be used when the style of the list allows selection.
 554          * @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 IconListView, then UpdateList() method should be called explicitly (e.g. during Tizen::Ui::Control::OnInitializing()).
 555          */
 556         bool IsItemChecked(int index) const;
 557
 558         /**
 559          * Gets the index of the item at the specified position.
 560          *
 561          * @since   2.0
 562          *
 563          * @return      The index of the item, @n
 564          *                      else @c -1 when there is no list item at the specified position or when the %IconListView instance is invalid
 565          * @param[in]   x                   The x position of a point
 566          * @param[in]   y                   The y position of a point
 567          */
 568         int GetItemIndexFromPosition(int x, int y) const;
 569
 570         /**
 571          * Gets the index of the item at the specified position.
 572          *
 573          * @since   2.1
 574          *
 575          * @return      The index of the item, @n
 576          *                      else @c -1 when there is no list item at the specified position or when the %IconListView instance is invalid
 577          * @param[in]   x                   The x position of a point
 578          * @param[in]   y                   The y position of a point
 579          */
 580         int GetItemIndexFromPosition(float x, float y) const;
 581
 582         /**
 583          * Gets the index of the item at the specified position.
 584          *
 585          * @since   2.0
 586          *
 587          * @return      The index of the item, @n
 588          *                      else @c -1 if there is no list item at the specified position or when the %IconListView instance is invalid
 589          * @param[in]   position            The position of a point
 590          */
 591         int GetItemIndexFromPosition(const Tizen::Graphics::Point& position) const;
 592
 593         /**
 594          * Gets the index of the item at the specified position.
 595          *
 596          * @since   2.1
 597          *
 598          * @return      The index of the item, @n
 599          *                      else @c -1 if there is no list item at the specified position or when the %IconListView instance is invalid
 600          * @param[in]   position            The position of a point
 601          */
 602         int GetItemIndexFromPosition(const Tizen::Graphics::FloatPoint& position) const;
 603
 604         /**
 605          * Sets the horizontal alignment of the text of an item.
 606          *
 607          * @since   2.0
 608          *
 609          * @return      An error code
 610          * @param[in]   alignment                       The horizontal alignment of the text
 611          * @exception   E_SUCCESS                       The method is successful.
 612          * @exception   E_SYSTEM                        A system error has occurred.
 613          */
 614         result SetTextHorizontalAlignment(HorizontalAlignment alignment);
 615
 616         /**
 617          * Sets the vertical alignment of the text of an item.
 618          *
 619          * @since   2.0
 620          *
 621          * @return      An error code
 622          * @param[in]   alignment                       The vertical alignment of the text
 623          * @exception   E_SUCCESS                       The method is successful.
 624          * @exception   E_SYSTEM                        A system error has occurred.
 625          */
 626         result SetTextVerticalAlignment(IconListViewItemTextVerticalAlignment alignment);
 627
 628         /**
 629          * Gets the horizontal alignment of the text of the %IconListView control.
 630          *
 631          * @since   2.0
 632          *
 633          * @return      The horizontal alignment of the text, @n
 634          *                      else ALIGNMENT_LEFT when the %IconListView instance is invalid
 635          */
 636         HorizontalAlignment GetTextHorizontalAlignment(void) const;
 637
 638         /**
 639          * Gets the vertical alignment of the text of the current %IconListView.
 640          *
 641          * @since   2.0
 642          *
 643          * @return      The vertical alignment of the text of an item, @n
 644          *                      else ICON_LIST_VIEW_ITEM_TEXT_VERTICAL_ALIGNMENT_INSIDE_TOP when the %IconListView is invalid
 645          */
 646         IconListViewItemTextVerticalAlignment GetTextVerticalAlignment(void) const;
 647
 648         /**
 649          * Sets the text of the empty list.
 650          *
 651          * @since   2.0
 652          *
 653          * @return      An error code
 654          * @param[in]   text                The text of the empty list
 655          * @exception   E_SUCCESS                       The method is successful.
 656          * @exception   E_SYSTEM                        A system error has occurred.
 657          */
 658         result SetTextOfEmptyList(const Tizen::Base::String& text);
 659
 660         /**
 661          * Gets the text to display when there is no item in the list.
 662          *
 663          * @since       2.0
 664          *
 665          * @return  The text to be displayed, @n
 666          *                      else an empty string if the instance is invalid
 667          */
 668         Tizen::Base::String GetTextOfEmptyList(void) const;
 669
 670         /**
 671          * Sets the color of the text that is displayed when %IconListView contains no item.
 672          *
 673          * @since   2.0
 674          *
 675          * @return      An error code
 676          * @param[in]   color               The color of the text
 677          * @exception   E_SUCCESS                       The method is successful.
 678          * @exception   E_SYSTEM                        A system error has occurred.
 679          */
 680         result SetTextColorOfEmptyList(const Tizen::Graphics::Color& color);
 681
 682         /**
 683          * Gets the color of the text to display when there is no item in the list.
 684          *
 685          * @since   2.0
 686          *
 687          * @return  The color of the text to be displayed, @n
 688          *                      else RGBA(0, 0, 0, 0) if the instance is invalid
 689          */
 690         Tizen::Graphics::Color GetTextColorOfEmptyList(void) const;
 691
 692         /**
 693          * Sets the text color of the item.
 694          *
 695          * @since   2.0
 696          *
 697          * @return      An error code
 698          * @param[in]   status                          The drawing status of items
 699          * @param[in]   color               The color of the text
 700          * @exception   E_SUCCESS                       The method is successful.
 701          * @exception   E_SYSTEM                        A system error has occurred.
 702          */
 703         result SetItemTextColor(IconListViewItemDrawingStatus status, const Tizen::Graphics::Color& color);
 704
 705         /**
 706          * Gets the text color of the item.
 707          *
 708          * @since   2.0
 709          *
 710          * @return      The color of the text, @n
 711          *                      else RGBA(0, 0, 0, 0) if the instance is invalid
 712          * @param[in]   status                          The drawing status of items
 713          */
 714         Tizen::Graphics::Color GetItemTextColor(IconListViewItemDrawingStatus status) const;
 715
 716         /**
 717          * Sets the size of the text of the %IconListView control.
 718          *
 719          * @since   2.0
 720          *
 721          * @return      An error code
 722          * @param[in]   size                            The size of the text
 723          * @exception   E_SUCCESS                       The method is successful.
 724          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 725          * @exception   E_SYSTEM                        A system error has occurred.
 726          * @remarks     If the specified @c size is less than the minimum size, this method fails. The minimum font size is @c 6 on devices of high screen density.
 727          */
 728         result SetItemTextSize(int size);
 729
 730         /**
 731          * Sets the size of the text of the %IconListView control.
 732          *
 733          * @since   2.1
 734          *
 735          * @return      An error code
 736          * @param[in]   size                            The size of the text
 737          * @exception   E_SUCCESS                       The method is successful.
 738          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 739          * @exception   E_SYSTEM                        A system error has occurred.
 740          * @remarks     If the specified @c size is less than the minimum size, this method fails. The minimum font size is @c 6 on devices of high screen density.
 741          */
 742         result SetItemTextSize(float size);
 743
 744         /**
 745          * Gets the size of the text of the %IconListView control.
 746          *
 747          * @since   2.0
 748          *
 749          * @return  The size of the text of the %IconListView control, else @c -1 if the instance is invalid
 750          */
 751         int GetItemTextSize(void) const;
 752
 753         /**
 754          * Gets the size of the text of the %IconListView control.
 755          *
 756          * @since   2.1
 757          *
 758          * @return  The size of the text of the %IconListView control, else @c -1.0f if the instance is invalid
 759          */
 760         float GetItemTextSizeF(void) const;
 761
 762         /**
 763          * Sets the position of the checkbox of the %IconListView control.
 764          *
 765          * @since   2.0
 766          *
 767          * @return      An error code
 768          * @param[in]   position                        The position of the checkbox of the %IconListView
 769          * @exception   E_SUCCESS                       The method is successful.
 770          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 771          *                                                                      That is, %IconListView cannot get the position of the checkbox when the style is ICON_LIST_VIEW_STYLE_NORMAL.
 772          * @exception   E_SYSTEM                        A system error has occurred.
 773          * @remarks  This method changes the position of the checkbox image displayed for the "selected" item(s),
 774          *                      when the style of %IconListView is either ICON_LIST_VIEW_STYLE_RADIO and ICON_LIST_VIEW_STYLE_MARK.
 775          */
 776         result SetCheckBoxPosition(IconListViewCheckBoxPosition position);
 777
 778         /**
 779          * Gets the position of the checkbox of the %IconListView control.
 780          *
 781          * @since   2.0
 782          *
 783          * @return      The position of the checkbox
 784          * @remarks     The method returns @c ICON_LIST_VIEW_CHECK_BOX_POSITION_TOP_LEFT when the style of %IconListView is ICON_LIST_VIEW_STYLE_NORMAL or
 785          *                      ICON_LIST_VIEW_STYLE_DIVIDE_TEXT.
 786          */
 787         IconListViewCheckBoxPosition GetCheckBoxPosition(void) const;
 788
 789         /**
 790          * Enables or disables touch animation.
 791          *
 792          * @since   2.0
 793          *
 794          * @return      An error code
 795          * @param[in]   enable                          Set to @c true to enable touch animation, @n
 796          *                                  else @c false
 797          * @exception   E_SUCCESS                       The method is successful.
 798          * @exception   E_SYSTEM                        A system error has occurred.
 799          * @remarks     If you want to use a separate selected bitmap, the animation effect must be disabled.
 800          * @remarks     In case that a touch animation disabled, the normal bitmap of %IconListViewItem is displayed in response to touch interaction if the
 801          *                      selected bitmap of %IconListViewItem is @c null.
 802          */
 803         result SetTouchAnimationEnabled(bool enable);
 804
 805         /**
 806          * Checks whether touch animation is enabled.
 807          *
 808          * @since   2.0
 809          *
 810          * @return      @c true if touch animation is enabled, @n
 811          *          else @c false if touch animation is disabled or when the instance is invalid
 812          */
 813         bool IsTouchAnimationEnabled(void) const;
 814
 815         /**
 816          * Scrolls the list contents to the specified index.
 817          *
 818          * @since   2.0
 819          *
 820          * @return      An error code
 821          * @param[in]   index                           The index of the item
 822          * @exception   E_SUCCESS                       The method is successful.
 823          * @exception   E_SYSTEM                        A system error has occurred.
 824          * @exception   E_OUT_OF_RANGE          The specified @c index is out of range.
 825          * @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 IconListView, then UpdateList() method should be called explicitly (e.g. during Tizen::Ui::Control::OnInitializing()).
 826          */
 827         result ScrollToItem(int index);
 828
 829         /*
 830          * Scrolls the list contents with the amount of pixels.
 831          *
 832          * @since 2.0
 833          *
 834          * @return      An error code
 835          * @param[in]   pixel                           The amount of pixels to scroll
 836          * @exception   E_SUCCESS                       The method is successful.
 837          * @exception   E_OUT_OF_RANGE          The specified @c pixel is out of range.
 838          * @remarks     If you call ScrollByPixel() with negative @c pixel when position of scroll is already top of contents then it will return E_OUT_OF_RANGE.
 839          *                      Likewise, in case of positive @c pixel on the bottom position of scroll it will also return E_OUT_OF_RANGE.
 840          */
 841         result ScrollByPixel(int pixel);
 842
 843         /*
 844          * Scrolls the list contents with the amount of pixels.
 845          *
 846          * @since 2.1
 847          *
 848          * @return      An error code
 849          * @param[in]   pixel                           The amount of pixels to scroll
 850          * @exception   E_SUCCESS                       The method is successful.
 851          * @exception   E_OUT_OF_RANGE          The specified @c pixel is out of range.
 852          * @remarks     If you call ScrollByPixel() with negative @c pixel when position of scroll is already top of contents then it will return E_OUT_OF_RANGE.
 853          *                      Likewise, in case of positive @c pixel on the bottom position of scroll it will also return E_OUT_OF_RANGE.
 854          */
 855         result ScrollByPixel(float pixel);
 856
 857         /**
 858          * Refreshes the specified item of %IconListView.
 859          *
 860          * @since   2.0
 861          *
 862          * @return      An error code
 863          * @param[in]   index                           The index of the %IconListView item
 864          * @param[in]   type                            The type of change of an item
 865          * @exception   E_SUCCESS                       The method is successful.
 866          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 867          *                                      That is, %IconListView cannot execute RefreshList() before first drawn.
 868          * @exception   E_SYSTEM                        A system error has occurred.
 869          * @exception   E_OUT_OF_RANGE          The specified @c index is out of range.
 870          */
 871         result RefreshList(int index, ListRefreshType type);
 872
 873         /**
 874          * Updates the whole items of a list.
 875          *
 876          * @since       2.0
 877          *
 878          * @return  An error code
 879          * @exception   E_SUCCESS           The method is successful.
 880          * @exception   E_SYSTEM            A system error has occurred.
 881          * @remarks  This method clears items in the list and re-invokes the methods of the item provider to fill the list.
 882          */
 883         result UpdateList(void);
 884
 885         /**
 886          * Gets the size of bitmap of the item.
 887          *
 888          * @since       2.0
 889          *
 890          * @return      An error code
 891          * @param[out]  width                           The width of bitmap of the item
 892          * @param[out]  height                          The height of bitmap of the item
 893          * @exception   E_SUCCESS                       The method is successful.
 894          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 895          */
 896         result GetItemBitmapSize(int& width, int& height) const;
 897
 898         /**
 899          * Gets the size of bitmap of the item.
 900          *
 901          * @since       2.1
 902          *
 903          * @return      An error code
 904          * @param[out]  width                           The width of bitmap of the item
 905          * @param[out]  height                          The height of bitmap of the item
 906          * @exception   E_SUCCESS                       The method is successful.
 907          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 908          */
 909         result GetItemBitmapSize(float& width, float& height) const;
 910
 911         /**
 912          * Gets the size of bitmap of the item.
 913          *
 914          * @since   2.0
 915          *
 916          * @return      The size of bitmap of the item, @n
 917          *                      else (-1, -1) if the instance is invalid
 918          */
 919         Tizen::Graphics::Dimension GetItemBitmapSize(void) const;
 920
 921         /**
 922          * Gets the size of bitmap of the item.
 923          *
 924          * @since   2.1
 925          *
 926          * @return      The size of bitmap of the item, @n
 927          *                      else (-1, -1) if the instance is invalid
 928          */
 929         Tizen::Graphics::FloatDimension GetItemBitmapSizeF(void) const;
 930
 931         /**
 932          * Gets the size of the item.
 933          *
 934          * @since   2.0
 935          *
 936          * @return      An error code
 937          * @param[out]  width                           The width of the item
 938          * @param[out]  height                          The height of the item
 939          * @exception   E_SUCCESS                       The method is successful.
 940          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 941          */
 942         result GetItemSize(int& width, int& height) const;
 943
 944         /**
 945          * Gets the size of the item.
 946          *
 947          * @since   2.1
 948          *
 949          * @return      An error code
 950          * @param[out]  width                           The width of the item
 951          * @param[out]  height                          The height of the item
 952          * @exception   E_SUCCESS                       The method is successful.
 953          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 954          */
 955         result GetItemSize(float& width, float& height) const;
 956
 957         /**
 958          * Gets the size of the item.
 959          *
 960          * @since   2.0
 961          *
 962          * @return      The size of the item, @n
 963          *                      else (-1, -1) if the instance is invalid
 964          */
 965         Tizen::Graphics::Dimension GetItemSize(void) const;
 966
 967         /**
 968          * Gets the size of the item.
 969          *
 970          * @since   2.1
 971          *
 972          * @return      The size of the item, @n
 973          *                      else (-1, -1) if the instance is invalid
 974          */
 975         Tizen::Graphics::FloatDimension GetItemSizeF(void) const;
 976
 977         /**
 978          * Sets the number of item lines to be scrolled for the magnetic scroll of %IconListView.
 979          *
 980          * @since   2.0
 981          *
 982          * @return      An error code
 983          * @param[in]   scrollSize                      The number of item lines for the magnetic scroll of %IconListView
 984          * @exception   E_SUCCESS                       The method is successful.
 985          * @exception   E_INVALID_ARG           The specified @c scrollSize is out of range. @n
 986          *                                                                      The specified @c scrollSize is less than @c 0 or greater than the item count shown along the scroll direction.
 987          * @exception   E_SYSTEM                        A system error has occurred.
 988          * @remarks     If the @c scrollSize is set to @c 0, %IconListView does not use the magnetic scroll. The initial value is @c 0.
 989          */
 990         result SetMagneticScrollSize(int scrollSize);
 991
 992         /**
 993          * Gets the number of item lines for the magnetic scroll of %IconListView.
 994          *
 995          * @since   2.0
 996          *
 997          * @return      The number of item lines for the magnetic scroll of %IconListView, @n
 998          *                      else @c -1 when the instance is invalid
 999          */
1000         int GetMagneticScrollSize(void) const;
1001
1002         /**
1003          * Gets the number of items to be displayed per axis of %IconListView.
1004          *
1005          * @since   2.0
1006          *
1007          * @return      The number of items to be displayed per axis, @n
1008          *                      else @c -1 if the instance is invalid
1009          * @remarks     The axis represents "row" when the scroll style is ICON_LIST_VIEW_SCROLLSDIRECTION_HORIZONTAL, while it represents "column" when the
1010          *                      scroll style is ICON_LIST_VIEW_SCROLLDIRECTION_VERTICAL.
1011          */
1012         int GetItemCountPerAxis(void) const;
1013
1014         /**
1015          * Sets the items horizontal alignment of %IconListView.
1016          *
1017          * @since   2.0
1018          *
1019          * @return      An error code
1020          * @param[in]   alignment                       The alignment of items
1021          * @exception   E_SUCCESS                       The method is successful.
1022          * @exception   E_INVALID_OPERATION     The alignment of icon list view is not in the vertical scroll direction.
1023          * @exception   E_SYSTEM                        A system error has occurred.
1024          */
1025         result SetItemLayoutHorizontalAlignment(HorizontalAlignment alignment);
1026
1027         /**
1028          * Sets the items vertical alignment of %IconListView.
1029          *
1030          * @since   2.0
1031          *
1032          * @return      An error code
1033          * @param[in]   alignment                       The alignment of items
1034          * @exception   E_SUCCESS                       The method is successful.
1035          * @exception   E_INVALID_OPERATION     The alignment of icon list view is not in the horizontal scroll direction.
1036          * @exception   E_SYSTEM                        A system error has occurred.
1037          */
1038         result SetItemLayoutVerticalAlignment(VerticalAlignment alignment);
1039
1040         /**
1041          * Gets the items horizontal alignment of %IconListView.
1042          *
1043          * @since   2.0
1044          *
1045          * @return      The alignment of items, @n
1046          *                      else @c ALIGNMENT_LEFT if the instance is invalid
1047          */
1048         HorizontalAlignment GetItemLayoutHorizontalAlignment(void) const;
1049
1050         /**
1051          * Gets the items vertical alignment of %IconListView.
1052          *
1053          * @since   2.0
1054          *
1055          * @return      The alignment of items, @n
1056          *                      else @c ALIGNMENT_TOP if the instance is invalid
1057          */
1058         VerticalAlignment GetItemLayoutVerticalAlignment(void) const;
1059
1060         /**
1061          * Sets the item border style.
1062          *
1063          * @since       2.0
1064          *
1065          * @return      An error code
1066          * @param[in]   borderStyle                     An item border style
1067          * @exception   E_SUCCESS                       The method is successful.
1068          * @exception   E_SYSTEM                        A system error has occurred.
1069         */
1070         result SetItemBorderStyle(IconListViewItemBorderStyle borderStyle);
1071
1072         /**
1073          * Gets the item border style.
1074          *
1075          * @since       2.0
1076          *
1077          * @return      The item border style, @n
1078          *                      else @c ICON_LIST_VIEW_ITEM_BORDER_STYLE_NONE if an error occurs
1079          */
1080         IconListViewItemBorderStyle GetItemBorderStyle(void) const;
1081
1082         /**
1083          * Sets the bitmap of the empty list.
1084          *
1085          * @since       2.0
1086          *
1087          * @return      An error code
1088          * @param[in]   pBitmap                         The bitmap of the empty list
1089          * @exception   E_SUCCESS                       The method is successful.
1090          * @exception   E_SYSTEM                        A system error has occurred.
1091          */
1092         result SetBitmapOfEmptyList(const Tizen::Graphics::Bitmap* pBitmap);
1093
1094         /**
1095          * Begins the reordering mode.
1096          *
1097          * @since 2.0
1098          *
1099          * @return  An error code
1100          * @exception E_SUCCESS         The method is successful.
1101          * @exception E_SYSTEM                  A system error has occurred.
1102          * @see IIconListViewItemEventListener::OnIconListViewItemReordered()
1103          */
1104         result BeginReorderingMode(void);
1105
1106         /**
1107          * Ends the reordering mode.
1108          *
1109          * @since 2.0
1110          *
1111          * @exception E_SUCCESS         The method is successful.
1112          * @exception E_SYSTEM                  A system error has occurred.
1113          * @see IIconListViewItemEventListener::OnIconListViewItemReordered()
1114          */
1115         result EndReorderingMode(void);
1116
1117         /**
1118          * Checks whether the %IconListView is in reordering mode.
1119          *
1120          * @since 2.0
1121          *
1122          * @return  @c true if the %IconListView is in reordering mode, @n
1123          *          else @c false
1124          */
1125         bool IsInReorderingMode(void) const;
1126
1127         /**
1128          * Sets the scroll input handling mode.
1129          *
1130          * @since 2.1
1131          *
1132          * @param[in] mode      The scroll input handling mode
1133          * @see                         GetScrollInputMode()
1134          */
1135         void SetScrollInputMode(ScrollInputMode mode);
1136
1137         /**
1138          * Gets the scroll input handling mode.
1139          *
1140          * @since 2.1
1141          *
1142          * @return              The scroll input handling mode
1143          * @see                 SetScrollInputMode()
1144          */
1145         ScrollInputMode GetScrollInputMode(void) const;
1146
1147 public:
1148         friend class _IconListViewImpl;
1149
1150 private:
1151         /**
1152          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1153          *
1154          * @since       2.0
1155          */
1156         IconListView(const IconListView& rhs);
1157
1158         /**
1159          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1160          *
1161          * @since       2.0
1162          */
1163         IconListView& operator =(const IconListView& rhs);
1164 }; // IconListView
1165
1166 }}} // Tizen::Ui::Controls
1167
1168 #endif // _FUI_CTRL_ICON_LIST_VIEW_H_