inc/FUiCtrlIconListView.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        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(const Tizen::Graphics::Rectangle&, const Tizen::Graphics::Dimension&, IconListViewStyle, IconListViewScrollDirection, IconListViewScrollStyle) 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 Tizen::Graphics::Rectangle class @n
 245          *                                                                      This instance represents the x and y coordinates of the top-left corner of the created %IconListView along with
 246          *                                                                      the width and height.@n
 247          *                                                                      The optimal size of the control is defined in
 248          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 249          * @param[in]   itemBitmapSize          The size of an icon in %IconListView
 250          * @param[in]   style                           The style set of %IconListView
 251          * @param[in]   direction                       The direction of scroll
 252          * @param[in]   scrollStyle                     The scroll style of %IconListView
 253          * @exception   E_SUCCESS                       The method is successful.
 254          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 255          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 256          * @exception   E_SYSTEM                        A system error has occurred.
 257          * @remarks     A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
 258          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and margins. @n
 259          *                      %IconListView cannot display more than @c 256 items on the screen at once.
 260          * @remarks     The actual size of bitmap to be displayed in %IconListView is smaller than the specified size when the border style is @c ICON_LIST_VIEW_ITEM_BORDER_STYLE_SHADOW.
 261          */
 262         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);
 263
 264         /**
 265          * Initializes this instance of %IconListView with the specified parameters.
 266          *
 267          * @since   2.1
 268          *
 269          * @return      An error code
 270          * @param[in]   rect                            An instance of the Tizen::Graphics::FloatRectangle class @n
 271          *                                                                      This instance represents the x and y coordinates of the top-left corner of the created %IconListView along with
 272          *                                                                      the width and height.@n
 273          *                                                                      The optimal size of the control is defined in
 274          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 275          * @param[in]   itemBitmapSize          The size of an icon in %IconListView
 276          * @param[in]   style                           The style set of %IconListView
 277          * @param[in]   direction                       The direction of scroll
 278          * @param[in]   scrollStyle                     The scroll style of %IconListView
 279          * @exception   E_SUCCESS                       The method is successful.
 280          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 281          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 282          * @exception   E_SYSTEM                        A system error has occurred.
 283          * @remarks     A control is fully usable only after it has been added to a container, therefore some methods may fail if used earlier.
 284          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and margins. @n
 285          *                      %IconListView cannot display more than @c 256 items on the screen at once.
 286          * @remarks     The actual size of bitmap to be displayed in %IconListView is smaller than the specified size when the border style is @c ICON_LIST_VIEW_ITEM_BORDER_STYLE_SHADOW.
 287          */
 288         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);
 289
 290         /**
 291          * Sets the item provider that creates and deletes items for the %IconListView control.
 292          *
 293          * @since   2.0
 294          *
 295          * @return      An error code
 296          * @param[in]   provider                        The item provider to create and delete items
 297          * @exception   E_SUCCESS                       The method is successful.
 298          * @exception   E_SYSTEM                        A system error has occurred.
 299          * @remarks     If an item provider is not set for %IconListView, it does not work. @n
 300          *                      The specified @c provider should be allocated in heap memory.
 301          */
 302         result SetItemProvider(IIconListViewItemProvider& provider);
 303
 304         /**
 305          * Adds a listener instance. @n
 306          * The added listener can listen to item events when they are fired.
 307          *
 308          * @since   2.0
 309          *
 310          * @param[in]   listener                        The listener to add
 311          */
 312         void AddIconListViewItemEventListener(IIconListViewItemEventListener& listener);
 313
 314         /**
 315          * Removes a listener instance. @n
 316          * The removed listener cannot listen to events when they are fired.
 317          *
 318          * @since   2.0
 319          *
 320          * @param[in]   listener                        The listener to remove
 321          */
 322         void RemoveIconListViewItemEventListener(IIconListViewItemEventListener& listener);
 323
 324         /**
 325          * Adds a listener instance that listens to state changes of a scroll event. @n
 326          * The added listener can listen to events on the context of the given event dispatcher when they are fired.
 327          *
 328          * @since   2.0
 329          *
 330          * @param[in]   listener                        The event listener to add
 331          * @see                 IScrollEventListener::OnScrollEndReached()
 332          * @see                 RemoveScrollEventListener()
 333          */
 334         void AddScrollEventListener(IScrollEventListener& listener);
 335
 336         /**
 337          * Adds a listener instance that listens to state changes of a scroll event. @n
 338          * The added listener can listen to events on the context of the given event dispatcher when they are fired.
 339          *
 340          * @since   2.1
 341          *
 342          * @param[in]   listener                        The event listener to add
 343          * @see                 IScrollEventListenerF::OnScrollEndReached()
 344          * @see                 RemoveScrollEventListener()
 345          */
 346         void AddScrollEventListener(IScrollEventListenerF& listener);
 347
 348         /**
 349          * Removes a listener instance that listens to state changes of a scroll event. @n
 350          * The removed listener cannot listen to events when they are fired.
 351          *
 352          * @since   2.0
 353          *
 354          * @param[in]   listener                        The event listener to remove
 355          * @see                 IScrollEventListener::OnScrollEndReached()
 356          * @see                 RemoveScrollEventListener()
 357          */
 358         void RemoveScrollEventListener(IScrollEventListener& listener);
 359
 360         /**
 361          * Removes a listener instance that listens to state changes of a scroll event. @n
 362          * The removed listener cannot listen to events when they are fired.
 363          *
 364          * @since   2.1
 365          *
 366          * @param[in]   listener                        The event listener to remove
 367          * @see                 IScrollEventListenerF::OnScrollEndReached()
 368          * @see                 RemoveScrollEventListener()
 369          */
 370         void RemoveScrollEventListener(IScrollEventListenerF& listener);
 371
 372         /**
 373          * Sets the background bitmap of %IconListView.
 374          *
 375          * @since   2.0
 376          *
 377          * @param[in]   pBitmap                         The background bitmap
 378          * @exception   E_SUCCESS                       The method is successful.
 379          * @exception   E_SYSTEM                        A system error has occurred.
 380          * @remarks     When @c pBitmap is @c null, %IconListView does not have a background bitmap. The default value for the background bitmap is @c null.
 381          * @remarks     The background bitmap has priority over the background color. When both the background bitmap and the background color are specified,
 382          *                      only the bitmap is displayed.
 383          */
 384         result SetBackgroundBitmap(const Tizen::Graphics::Bitmap* pBitmap);
 385
 386         /**
 387          * Sets the background color of this control.
 388          *
 389          * @since   2.0
 390          *
 391          * @return      An error code
 392          * @param[in]   color               The background color
 393          * @exception   E_SUCCESS                       The method is successful.
 394          * @remarks     This method sets the alpha value of the specified color to @c 255, when a device does not support @c 32 bit color space.
 395          * @remarks     The background bitmap has priority over the background color. When both the background bitmap and the background color are specified,
 396          *                      only the bitmap is displayed.
 397          */
 398         result SetBackgroundColor(const Tizen::Graphics::Color& color);
 399
 400         /**
 401          * Gets the background color of this control.
 402          *
 403          * @since       2.0
 404          *
 405          * @return      The background color, @n
 406          *                      else RGBA(0, 0, 0, 0) if an error occurs
 407          */
 408         Tizen::Graphics::Color GetBackgroundColor(void) const;
 409
 410         /**
 411          * Sets the margin of %IconListView.
 412          *
 413          * @since   2.0
 414          *
 415          * @return      An error code
 416          * @param[in]   type                            The type of margin
 417          * @param[in]   value                           The marginal value
 418          * @exception   E_SUCCESS                       The method is successful.
 419          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 420          * @exception   E_SYSTEM                        A system error has occurred.
 421          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and
 422          *                      margins. %IconListView cannot display more than @c 256 items on screen at once.
 423          */
 424         result SetMargin(MarginType type, int value);
 425
 426         /**
 427          * Sets the margin of %IconListView.
 428          *
 429          * @since   2.1
 430          *
 431          * @return      An error code
 432          * @param[in]   type                            The type of margin
 433          * @param[in]   value                           The marginal value
 434          * @exception   E_SUCCESS                       The method is successful.
 435          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 436          * @exception   E_SYSTEM                        A system error has occurred.
 437          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and
 438          *                      margins. The %IconListView cannot display more than 256 items on screen at once.
 439          */
 440         result SetMargin(MarginType type, float value);
 441
 442         /**
 443          * Gets the margin of %IconListView.
 444          *
 445          * @since   2.0
 446          *
 447          * @return      The marginal value of %IconListView, @n
 448          *                      else @c -1 if an error occurs
 449          * @param[in]   type                            The type of margin
 450          */
 451         int GetMargin(MarginType type) const;
 452
 453         /**
 454          * Gets the margin of %IconListView.
 455          *
 456          * @since   2.1
 457          *
 458          * @return      The marginal value of %IconListView, @n
 459          *                      else @c -1 if an error occurs
 460          * @param[in]   type                            The type of margin
 461          */
 462         float GetMarginF(MarginType type) const;
 463
 464         /**
 465          * Sets the horizontal and vertical spacing between the items.
 466          *
 467          * @since   2.0
 468          *
 469          * @return      An error code
 470          * @param[in]   horizontalSpacing       The spacing between items in horizontal direction
 471          * @param[in]   verticalSpacing         The spacing between items in vertical direction
 472          * @exception   E_SUCCESS                       The method is successful.
 473          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 474          * @exception   E_SYSTEM                        A system error has occurred.
 475          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and
 476          *                      margins. %IconListView cannot display more than @c 256 items on screen at once.
 477          */
 478         result SetItemSpacing(int horizontalSpacing, int verticalSpacing);
 479
 480         /**
 481          * Sets the horizontal and vertical spacing between the items.
 482          *
 483          * @since   2.1
 484          *
 485          * @return      An error code
 486          * @param[in]   horizontalSpacing       The spacing between items in horizontal direction
 487          * @param[in]   verticalSpacing         The spacing between items in vertical direction
 488          * @exception   E_SUCCESS                       The method is successful.
 489          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 490          * @exception   E_SYSTEM                        A system error has occurred.
 491          * @remarks     The number of items to be displayed on a screen is calculated based on %IconListView size, item size, item spacing, and
 492          *                      margins. The %IconListView cannot display more than 256 items on screen at once.
 493          */
 494         result SetItemSpacing(float horizontalSpacing, float verticalSpacing);
 495
 496         /**
 497          * Gets the horizontal spacing between items of %IconListView.
 498          *
 499          * @since   2.0
 500          *
 501          * @return      The value of space between items in horizontal direction, @n
 502          *                      else @c -1 if an error occurs
 503          */
 504         int GetItemHorizontalSpacing(void) const;
 505
 506         /**
 507          * Gets the horizontal spacing between items of %IconListView.
 508          *
 509          * @since   2.1
 510          *
 511          * @return      The value of space between items in horizontal direction, @n
 512          *                      else @c -1 if an error occurs
 513          */
 514         float GetItemHorizontalSpacingF(void) const;
 515
 516         /**
 517          * Gets the vertical spacing between items of %IconListView.
 518          *
 519          * @since   2.0
 520          *
 521          * @return      The value of space between items in vertical direction, @n
 522          *                      else @c -1 if an error occurs
 523          */
 524         int GetItemVerticalSpacing(void) const;
 525
 526         /**
 527          * Gets the vertical spacing between items of %IconListView.
 528          *
 529          * @since   2.1
 530          *
 531          * @return      The value of space between items in vertical direction, @n
 532          *                      else @c -1 if an error occurs
 533          */
 534         float GetItemVerticalSpacingF(void) const;
 535
 536         /**
 537          * Sets the checked status of the specified item of %IconListView.
 538          *
 539          * @since   2.0
 540          *
 541          * @return      An error code
 542          * @param[in]   index                           The index of the %IconListView item
 543          * @param[in]   check                           The check status
 544          * @exception   E_SUCCESS                       The method is successful.
 545          * @exception   E_SYSTEM                        A system error has occurred.
 546          * @exception   E_OUT_OF_RANGE          The specified @c index is out of range.
 547          * @remarks     This method can only be used when the style of the list allows selection.
 548          * @remarks     This method only changes the state of the list item. %IconListView needs to be redrawn to reflect the change on the screen.
 549          */
 550         result SetItemChecked(int index, bool check);
 551
 552         /**
 553          * Checks whether the specified @c item is checked.
 554          *
 555          * @since   2.0
 556          *
 557          * @return      @c true if the specified @c item is checked, @n
 558          *                      else @c false
 559          * @param[in]   index                           The index of the item
 560          * @remarks  This method can only be used when the style of the list allows selection.
 561          */
 562         bool IsItemChecked(int index) const;
 563
 564         /**
 565          * Gets the index of the item at the specified position.
 566          *
 567          * @since   2.0
 568          *
 569          * @return      The index of the item, @n
 570          *                      else @c -1 if there is no list item at the specified position or if the %IconListView instance is invalid
 571          * @param[in]   x                   The x position of a point
 572          * @param[in]   y                   The y position of a point
 573          */
 574         int GetItemIndexFromPosition(int x, int y) const;
 575
 576         /**
 577          * Gets the index of the item at the specified @c position.
 578          *
 579          * @since   2.1
 580          *
 581          * @return      The index of the item, @n
 582          *                      else @c -1 if there is no list item at the specified position or if the %IconListView instance is invalid
 583          * @param[in]   x                   The x position of a point
 584          * @param[in]   y                   The y position of a point
 585          */
 586         int GetItemIndexFromPosition(float x, float y) const;
 587
 588         /**
 589          * Gets the index of the item at the specified position.
 590          *
 591          * @since   2.0
 592          *
 593          * @return      The index of the item, @n
 594          *                      else @c -1 if there is no list item at the specified @c position or if the %IconListView instance is invalid
 595          * @param[in]   position            The position of a point
 596          */
 597         int GetItemIndexFromPosition(const Tizen::Graphics::Point& position) const;
 598
 599         /**
 600          * Gets the index of the item at the specified position.
 601          *
 602          * @since   2.1
 603          *
 604          * @return      The index of the item, @n
 605          *                      else @c -1 if there is no list item at the specified @c position or if the %IconListView instance is invalid
 606          * @param[in]   position            The position of a point
 607          */
 608         int GetItemIndexFromPosition(const Tizen::Graphics::FloatPoint& position) const;
 609
 610         /**
 611          * Sets the horizontal alignment of the text of an item.
 612          *
 613          * @since   2.0
 614          *
 615          * @return      An error code
 616          * @param[in]   alignment                       The horizontal alignment of the text
 617          * @exception   E_SUCCESS                       The method is successful.
 618          * @exception   E_SYSTEM                        A system error has occurred.
 619          */
 620         result SetTextHorizontalAlignment(HorizontalAlignment alignment);
 621
 622         /**
 623          * Sets the vertical alignment of the text of an item.
 624          *
 625          * @since   2.0
 626          *
 627          * @return      An error code
 628          * @param[in]   alignment                       The vertical alignment of the text
 629          * @exception   E_SUCCESS                       The method is successful.
 630          * @exception   E_SYSTEM                        A system error has occurred.
 631          */
 632         result SetTextVerticalAlignment(IconListViewItemTextVerticalAlignment alignment);
 633
 634         /**
 635          * Gets the horizontal alignment of the text of the %IconListView control.
 636          *
 637          * @since   2.0
 638          *
 639          * @return      The horizontal alignment of the text, @n
 640          *                      else @c ALIGNMENT_LEFT when the %IconListView instance is invalid
 641          */
 642         HorizontalAlignment GetTextHorizontalAlignment(void) const;
 643
 644         /**
 645          * Gets the vertical alignment of the text of the current %IconListView.
 646          *
 647          * @since   2.0
 648          *
 649          * @return      The vertical alignment of the text of an item, @n
 650          *                      else @c ICON_LIST_VIEW_ITEM_TEXT_VERTICAL_ALIGNMENT_INSIDE_TOP when the %IconListView instance is invalid
 651          */
 652         IconListViewItemTextVerticalAlignment GetTextVerticalAlignment(void) const;
 653
 654         /**
 655          * Sets the text of the empty list.
 656          *
 657          * @since   2.0
 658          *
 659          * @return      An error code
 660          * @param[in]   text                The text of the empty list
 661          * @exception   E_SUCCESS                       The method is successful.
 662          * @exception   E_SYSTEM                        A system error has occurred.
 663          */
 664         result SetTextOfEmptyList(const Tizen::Base::String& text);
 665
 666         /**
 667          * Gets the text to display when there is no item in the list.
 668          *
 669          * @since       2.0
 670          *
 671          * @return  The text to be displayed, @n
 672          *                      else an empty string if the instance is invalid
 673          */
 674         Tizen::Base::String GetTextOfEmptyList(void) const;
 675
 676         /**
 677          * Sets the color of the text that is displayed when %IconListView contains no item.
 678          *
 679          * @since   2.0
 680          *
 681          * @return      An error code
 682          * @param[in]   color               The color of the text
 683          * @exception   E_SUCCESS                       The method is successful.
 684          * @exception   E_SYSTEM                        A system error has occurred.
 685          */
 686         result SetTextColorOfEmptyList(const Tizen::Graphics::Color& color);
 687
 688         /**
 689          * Gets the color of the text to display when there is no item in the list.
 690          *
 691          * @since   2.0
 692          *
 693          * @return  The color of the text to be displayed, @n
 694          *                      else RGBA(0, 0, 0, 0) if the instance is invalid
 695          */
 696         Tizen::Graphics::Color GetTextColorOfEmptyList(void) const;
 697
 698         /**
 699          * Sets the text color of the item.
 700          *
 701          * @since   2.0
 702          *
 703          * @return      An error code
 704          * @param[in]   status                          The drawing status of items
 705          * @param[in]   color               The color of the text
 706          * @exception   E_SUCCESS                       The method is successful.
 707          * @exception   E_SYSTEM                        A system error has occurred.
 708          */
 709         result SetItemTextColor(IconListViewItemDrawingStatus status, const Tizen::Graphics::Color& color);
 710
 711         /**
 712          * Gets the text color of the item.
 713          *
 714          * @since   2.0
 715          *
 716          * @return      The color of the text, @n
 717          *                      else RGBA(0, 0, 0, 0) if the instance is invalid
 718          * @param[in]   status                          The drawing status of items
 719          */
 720         Tizen::Graphics::Color GetItemTextColor(IconListViewItemDrawingStatus status) const;
 721
 722         /**
 723          * Sets the size of the text of the %IconListView control.
 724          *
 725          * @since   2.0
 726          *
 727          * @return      An error code
 728          * @param[in]   size                            The size of the text
 729          * @exception   E_SUCCESS                       The method is successful.
 730          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 731          * @exception   E_SYSTEM                        A system error has occurred.
 732          * @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.
 733          */
 734         result SetItemTextSize(int size);
 735
 736         /**
 737          * Sets the size of the text of the %IconListView control.
 738          *
 739          * @since   2.1
 740          *
 741          * @return      An error code
 742          * @param[in]   size                            The size of the text
 743          * @exception   E_SUCCESS                       The method is successful.
 744          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 745          * @exception   E_SYSTEM                        A system error has occurred.
 746          * @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.
 747          */
 748         result SetItemTextSize(float size);
 749
 750         /**
 751          * Gets the size of the text of the %IconListView control.
 752          *
 753          * @since   2.0
 754          *
 755          * @return  The size of the text of the %IconListView control, @n
 756          *                      else @c -1 if the instance is invalid
 757          */
 758         int GetItemTextSize(void) const;
 759
 760         /**
 761          * Gets the size of the text of the %IconListView control.
 762          *
 763          * @since   2.1
 764          *
 765          * @return  The size of the text of the %IconListView control, @n
 766          *                      else @c -1 if the instance is invalid
 767          */
 768         float GetItemTextSizeF(void) const;
 769
 770         /**
 771          * Sets the position of the checkbox of the %IconListView control.
 772          *
 773          * @since   2.0
 774          *
 775          * @return      An error code
 776          * @param[in]   position                        The position of the checkbox of the %IconListView control
 777          * @exception   E_SUCCESS                       The method is successful.
 778          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 779          *                                                                      That is, %IconListView cannot get the position of the checkbox when the style is @c ICON_LIST_VIEW_STYLE_NORMAL.
 780          * @exception   E_SYSTEM                        A system error has occurred.
 781          * @remarks  This method changes the position of the checkbox image displayed for the "selected" item(s),
 782          *                      when the style of %IconListView is either @c ICON_LIST_VIEW_STYLE_RADIO or @c ICON_LIST_VIEW_STYLE_MARK.
 783          */
 784         result SetCheckBoxPosition(IconListViewCheckBoxPosition position);
 785
 786         /**
 787          * Gets the position of the checkbox of the %IconListView control.
 788          *
 789          * @since   2.0
 790          *
 791          * @return      The position of the checkbox
 792          * @remarks     This method returns @c ICON_LIST_VIEW_CHECK_BOX_POSITION_TOP_LEFT when the style of %IconListView is @c ICON_LIST_VIEW_STYLE_NORMAL or
 793          *                      @c ICON_LIST_VIEW_STYLE_DIVIDE_TEXT.
 794          */
 795         IconListViewCheckBoxPosition GetCheckBoxPosition(void) const;
 796
 797         /**
 798          * Enables or disables touch animation.
 799          *
 800          * @since   2.0
 801          *
 802          * @return      An error code
 803          * @param[in]   enable                          Set to @c true to enable touch animation, @n
 804          *                                  else @c false
 805          * @exception   E_SUCCESS                       The method is successful.
 806          * @exception   E_SYSTEM                        A system error has occurred.
 807          * @remarks     If you want to use a separate selected bitmap, the animation effect must be disabled.
 808          * @remarks     In case a touch animation is disabled, the normal bitmap of IconListViewItem is displayed in response to touch interaction if the
 809          *                      selected bitmap of %IconListViewItem is @c null.
 810          */
 811         result SetTouchAnimationEnabled(bool enable);
 812
 813         /**
 814          * Checks whether touch animation is enabled.
 815          *
 816          * @since   2.0
 817          *
 818          * @return      @c true if touch animation is enabled, @n
 819          *          else @c false if touch animation is disabled or if the instance is invalid
 820          */
 821         bool IsTouchAnimationEnabled(void) const;
 822
 823         /**
 824          * Scrolls the list contents to the specified @c index.
 825          *
 826          * @since   2.0
 827          *
 828          * @return      An error code
 829          * @param[in]   index                           The index of the item
 830          * @exception   E_SUCCESS                       The method is successful.
 831          * @exception   E_SYSTEM                        A system error has occurred.
 832          * @exception   E_OUT_OF_RANGE          The specified @c index is out of range.
 833          */
 834         result ScrollToItem(int index);
 835
 836         /*
 837          * Scrolls the list contents with the amount of pixels.
 838          *
 839          * @since 2.1
 840          *
 841          * @return      An error code
 842          * @param[in]   pixel                           The amount of pixels to scroll
 843          * @exception   E_SUCCESS                       The method is successful.
 844          * @exception   E_OUT_OF_RANGE          The specified @c pixel is out of range.
 845          * @remarks     If you call ScrollByPixel() with negative @c pixel when position of scroll is already top of contents then it will return @c E_OUT_OF_RANGE.
 846          *                      Likewise, in case of positive @c pixel on the bottom position of scroll it will also return @c E_OUT_OF_RANGE.
 847          */
 848         result ScrollByPixel(int pixel);
 849
 850         /*
 851          * Scrolls the list contents with the amount of pixels.
 852          *
 853          * @since 2.1
 854          *
 855          * @return      An error code
 856          * @param[in]   pixel                           The amount of pixels to scroll
 857          * @exception   E_SUCCESS                       The method is successful.
 858          * @exception   E_OUT_OF_RANGE          The specified @c pixel is out of range.
 859          * @remarks     If you call ScrollByPixel() with negative @c pixel when position of scroll is already top of contents then it will return @c E_OUT_OF_RANGE.
 860          *                      Likewise, in case of positive @c pixel on the bottom position of scroll it will also return @c E_OUT_OF_RANGE.
 861          */
 862         result ScrollByPixel(float pixel);
 863
 864         /**
 865          * Refreshes the specified item of %IconListView.
 866          *
 867          * @since   2.0
 868          *
 869          * @return      An error code
 870          * @param[in]   index                           The index of the %IconListView item
 871          * @param[in]   type                            The type of change of an item
 872          * @exception   E_SUCCESS                       The method is successful.
 873          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation. @n
 874          *                                      That is, %IconListView cannot execute RefreshList() before first drawn.
 875          * @exception   E_SYSTEM                        A system error has occurred.
 876          * @exception   E_OUT_OF_RANGE          The specified @c index is out of range.
 877          */
 878         result RefreshList(int index, ListRefreshType type);
 879
 880         /**
 881          * Updates the whole items of a list.
 882          *
 883          * @since       2.0
 884          *
 885          * @return  An error code
 886          * @exception   E_SUCCESS           The method is successful.
 887          * @exception   E_SYSTEM            A system error has occurred.
 888          * @remarks  This method clears items in the list and re-invokes the methods of the item provider to fill the list.
 889          */
 890         result UpdateList(void);
 891
 892         /**
 893          * Gets the size of bitmap of the item.
 894          *
 895          * @since       2.0
 896          *
 897          * @return      An error code
 898          * @param[out]  width                           The width of bitmap of the item
 899          * @param[out]  height                          The height of bitmap of the item
 900          * @exception   E_SUCCESS                       The method is successful.
 901          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 902          */
 903         result GetItemBitmapSize(int& width, int& height) const;
 904
 905         /**
 906          * Gets the size of bitmap of the item.
 907          *
 908          * @since       2.1
 909          *
 910          * @return      An error code
 911          * @param[out]  width                           The width of bitmap of the item
 912          * @param[out]  height                          The height of bitmap of the item
 913          * @exception   E_SUCCESS                       The method is successful.
 914          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 915          */
 916         result GetItemBitmapSize(float& width, float& height) const;
 917
 918         /**
 919          * Gets the size of bitmap of the item.
 920          *
 921          * @since   2.0
 922          *
 923          * @return      The size of bitmap of the item, @n
 924          *                      else (-1, -1) if the instance is invalid
 925          */
 926         Tizen::Graphics::Dimension GetItemBitmapSize(void) const;
 927
 928         /**
 929          * Gets the size of bitmap of the item.
 930          *
 931          * @since   2.1
 932          *
 933          * @return      The size of bitmap of the item, @n
 934          *                      else (-1, -1) if the instance is invalid
 935          */
 936         Tizen::Graphics::FloatDimension GetItemBitmapSizeF(void) const;
 937
 938         /**
 939          * Gets the size of the item.
 940          *
 941          * @since   2.0
 942          *
 943          * @return      An error code
 944          * @param[out]  width                           The width of the item
 945          * @param[out]  height                          The height of the item
 946          * @exception   E_SUCCESS                       The method is successful.
 947          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 948          */
 949         result GetItemSize(int& width, int& height) const;
 950
 951         /**
 952          * Gets the size of the item.
 953          *
 954          * @since   2.1
 955          *
 956          * @return      An error code
 957          * @param[out]  width                           The width of the item
 958          * @param[out]  height                          The height of the item
 959          * @exception   E_SUCCESS                       The method is successful.
 960          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 961          */
 962         result GetItemSize(float& width, float& height) const;
 963
 964         /**
 965          * Gets the size of the item.
 966          *
 967          * @since   2.0
 968          *
 969          * @return      The size of the item, @n
 970          *                      else (-1, -1) if the instance is invalid
 971          */
 972         Tizen::Graphics::Dimension GetItemSize(void) const;
 973
 974         /**
 975          * Gets the size of the item.
 976          *
 977          * @since   2.1
 978          *
 979          * @return      The size of the item, @n
 980          *                      else (-1, -1) if the instance is invalid
 981          */
 982         Tizen::Graphics::FloatDimension GetItemSizeF(void) const;
 983
 984         /**
 985          * Sets the number of item lines to be scrolled for the magnetic scroll of %IconListView.
 986          *
 987          * @since   2.0
 988          *
 989          * @return      An error code
 990          * @param[in]   scrollSize                      The number of item lines for the magnetic scroll of %IconListView
 991          * @exception   E_SUCCESS                       The method is successful.
 992          * @exception   E_INVALID_ARG           The specified @c scrollSize is out of range. @n
 993          *                                                                      The specified @c scrollSize is less than @c 0 or greater than the item count shown along the scroll direction.
 994          * @exception   E_SYSTEM                        A system error has occurred.
 995          * @remarks     If the @c scrollSize is set to @c 0, %IconListView does not use the magnetic scroll. The initial value is @c 0.
 996          */
 997         result SetMagneticScrollSize(int scrollSize);
 998
 999         /**
1000          * Gets the number of item lines for the magnetic scroll of %IconListView.
1001          *
1002          * @since   2.0
1003          *
1004          * @return      The number of item lines for the magnetic scroll of %IconListView, @n
1005          *                      else @c -1 if the instance is invalid
1006          */
1007         int GetMagneticScrollSize(void) const;
1008
1009         /**
1010          * Gets the number of items to be displayed per axis of %IconListView.
1011          *
1012          * @since   2.0
1013          *
1014          * @return      The number of items to be displayed per axis, @n
1015          *                      else @c -1 if the instance is invalid
1016          * @remarks     The axis represents "row" when the scroll style is @c ICON_LIST_VIEW_SCROLLSDIRECTION_HORIZONTAL, while it represents "column" when the
1017          *                      scroll style is @c ICON_LIST_VIEW_SCROLLDIRECTION_VERTICAL.
1018          */
1019         int GetItemCountPerAxis(void) const;
1020
1021         /**
1022          * Sets the items horizontal alignment of %IconListView.
1023          *
1024          * @since   2.0
1025          *
1026          * @return      An error code
1027          * @param[in]   alignment                       The alignment of items
1028          * @exception   E_SUCCESS                       The method is successful.
1029          * @exception   E_INVALID_OPERATION     The alignment of icon list view is not in the vertical scroll direction.
1030          * @exception   E_SYSTEM                        A system error has occurred.
1031          */
1032         result SetItemLayoutHorizontalAlignment(HorizontalAlignment alignment);
1033
1034         /**
1035          * Sets the items vertical alignment of %IconListView.
1036          *
1037          * @since   2.0
1038          *
1039          * @return      An error code
1040          * @param[in]   alignment                       The alignment of items
1041          * @exception   E_SUCCESS                       The method is successful.
1042          * @exception   E_INVALID_OPERATION     The alignment of icon list view is not in the horizontal scroll direction.
1043          * @exception   E_SYSTEM                        A system error has occurred.
1044          */
1045         result SetItemLayoutVerticalAlignment(VerticalAlignment alignment);
1046
1047         /**
1048          * Gets the items horizontal alignment of %IconListView.
1049          *
1050          * @since   2.0
1051          *
1052          * @return      The alignment of items, @n
1053          *                      else @c ALIGNMENT_LEFT if the instance is invalid
1054          */
1055         HorizontalAlignment GetItemLayoutHorizontalAlignment(void) const;
1056
1057         /**
1058          * Gets the items vertical alignment of %IconListView.
1059          *
1060          * @since   2.0
1061          *
1062          * @return      The alignment of items, @n
1063          *                      else @c ALIGNMENT_TOP if the instance is invalid
1064          */
1065         VerticalAlignment GetItemLayoutVerticalAlignment(void) const;
1066
1067         /**
1068          * Sets the item border style.
1069          *
1070          * @since       2.0
1071          *
1072          * @return      An error code
1073          * @param[in]   borderStyle                     An item border style
1074          * @exception   E_SUCCESS                       The method is successful.
1075          * @exception   E_SYSTEM                        A system error has occurred.
1076         */
1077         result SetItemBorderStyle(IconListViewItemBorderStyle borderStyle);
1078
1079         /**
1080          * Gets the item border style.
1081          *
1082          * @since       2.0
1083          *
1084          * @return      The item border style, @n
1085          *                      else @c ICON_LIST_VIEW_ITEM_BORDER_STYLE_NONE if an error occurs
1086          */
1087         IconListViewItemBorderStyle GetItemBorderStyle(void) const;
1088
1089         /**
1090          * Sets the bitmap of the empty list.
1091          *
1092          * @since       2.0
1093          *
1094          * @return      An error code
1095          * @param[in]   pBitmap                         The bitmap of the empty list
1096          * @exception   E_SUCCESS                       The method is successful.
1097          * @exception   E_SYSTEM                        A system error has occurred.
1098          */
1099         result SetBitmapOfEmptyList(const Tizen::Graphics::Bitmap* pBitmap);
1100
1101         /**
1102          * Begins the reordering mode.
1103          *
1104          * @since 2.0
1105          *
1106          * @return  An error code
1107          * @exception E_SUCCESS         The method is successful.
1108          * @exception E_SYSTEM                  A system error has occurred.
1109          * @see IIconListViewItemEventListener::OnIconListViewItemReordered()
1110          */
1111         result BeginReorderingMode(void);
1112
1113         /**
1114          * Ends the reordering mode.
1115          *
1116          * @since 2.0
1117          *
1118          * @exception E_SUCCESS         The method is successful.
1119          * @exception E_SYSTEM                  A system error has occurred.
1120          * @see IIconListViewItemEventListener::OnIconListViewItemReordered()
1121          */
1122         result EndReorderingMode(void);
1123
1124         /**
1125          * Checks whether %IconListView is in reordering mode.
1126          *
1127          * @since 2.0
1128          *
1129          * @return  @c true if %IconListView is in reordering mode, @n
1130          *          else @c false
1131          */
1132         bool IsInReorderingMode(void) const;
1133
1134         /**
1135          * Sets the scroll input handling mode.
1136          *
1137          * @since 2.1
1138          *
1139          * @param[in] mode      The scroll input handling mode
1140          * @see                         GetScrollInputMode()
1141          */
1142         void SetScrollInputMode(ScrollInputMode mode);
1143
1144         /**
1145          * Gets the scroll input handling mode.
1146          *
1147          * @since 2.1
1148          *
1149          * @return              The scroll input handling mode
1150          * @see                 SetScrollInputMode()
1151          */
1152         ScrollInputMode GetScrollInputMode(void) const;
1153
1154 public:
1155         friend class _IconListViewImpl;
1156
1157 private:
1158         /**
1159          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1160          *
1161          * @since       2.0
1162          */
1163         IconListView(const IconListView& rhs);
1164
1165         /**
1166          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1167          *
1168          * @since       2.0
1169          */
1170         IconListView& operator =(const IconListView& rhs);
1171
1172 }; // IconListView
1173
1174 }}} // Tizen::Ui::Controls
1175
1176 #endif // _FUI_CTRL_ICON_LIST_VIEW_H_