inc/FUiCtrlTableView.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 FUiCtrlTableView.h
  20  * @brief This is the header file for the %TableView class.
  21  *
  22  * This header file contains the declarations of the %TableView class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_TABLE_VIEW_H_
  26 #define _FUI_CTRL_TABLE_VIEW_H_
  27
  28 #include <FGrpRectangle.h>
  29 #include <FGrpColor.h>
  30 #include <FUiContainer.h>
  31 #include <FUiCtrlTableViewTypes.h>
  32
  33 namespace Tizen { namespace Ui { namespace Controls
  34 {
  35 class ITableViewItemProvider;
  36 class ITableViewItemEventListener;
  37 class IFastScrollListener;
  38 class IScrollEventListener;
  39
  40 /**
  41  * @class TableView
  42  * @brief   This class defines common behavior for a %TableView control.
  43  *
  44  * @since 2.0
  45  *
  46  * The %TableView class defines common behavior for a %TableView control.
  47  * @code
  48 //Sample code for TableViewSample.h
  49 #include <FUi.h>
  50
  51 class TableViewSample
  52         : public Tizen::Ui::Controls::Form
  53         , public Tizen::Ui::Controls::ITableViewItemProvider
  54         , public Tizen::Ui::Controls::ITableViewItemEventListener
  55 {
  56 public:
  57         TableViewSample(void)
  58         : __pTableView(null)
  59         , __pContextItem(null){}
  60
  61         bool Initialize(void);
  62         virtual result OnInitializing(void);
  63         virtual result OnTerminating(void);
  64
  65         // ITableViewItemEventListener
  66         virtual void OnTableViewItemStateChanged(Tizen::Ui::Controls::TableView& tableView, int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem, Tizen::Ui::Controls::TableViewItemStatus status);
  67         virtual void OnTableViewContextItemActivationStateChanged(Tizen::Ui::Controls::TableView& tableView, int itemIndex, Tizen::Ui::Controls::TableViewContextItem* pContextItem, bool activated);
  68         virtual void OnTableViewItemReordered(Tizen::Ui::Controls::TableView& tableView, int itemIndexFrom, int itemIndexTo);
  69
  70         // ITableViewItemProvider
  71         virtual int GetItemCount(void);
  72         virtual Tizen::Ui::Controls::TableViewItem* CreateItem(int itemIndex, int itemWidth);
  73         virtual bool DeleteItem(int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem);
  74         virtual void UpdateItem(int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem);
  75         virtual int GetDefaultItemHeight(void);
  76
  77 private:
  78         Tizen::Ui::Controls::TableView* __pTableView;
  79         Tizen::Ui::Controls::TableViewContextItem* __pContextItem;
  80 };
  81  *      @endcode
  82  *
  83  *      @code
  84 //Sample code for TableViewSample.cpp
  85 #include <FApp.h>
  86 #include <FGraphics.h>
  87
  88 #include "TableViewSample.h"
  89
  90 using namespace Tizen::App;
  91 using namespace Tizen::Base;
  92 using namespace Tizen::Graphics;
  93 using namespace Tizen::Media;
  94 using namespace Tizen::Ui::Controls;
  95
  96 bool
  97 TableViewSample::Initialize(void)
  98 {
  99         Construct(FORM_STYLE_NORMAL);
 100         return true;
 101 }
 102
 103 result
 104 TableViewSample::OnInitializing(void)
 105 {
 106         result r = E_SUCCESS;
 107
 108         // Creates an instance of TableView
 109         __pTableView = new TableView();
 110         __pTableView->Construct(Rectangle(0, 0, GetClientAreaBounds().width, GetClientAreaBounds().height), true, TABLE_VIEW_SCROLL_BAR_STYLE_FADE_OUT);
 111         __pTableView->SetItemProvider(*this);
 112         __pTableView->AddTableViewItemEventListener(*this);
 113
 114         // Adds the TableView to the form
 115         AddControl(*__pTableView);
 116
 117         // Creates an instance of TableViewContextItem
 118         __pContextItem = new TableViewContextItem();
 119         __pContextItem->Construct(Dimension(720, 100));
 120
 121         Button* pButton = new Button();
 122         pButton->Construct(Rectangle(10, 10, 200, 80), L"Context1");
 123
 124         Button* pButton2 = new Button();
 125         pButton2->Construct(Rectangle(250, 10, 200, 80), L"Context2");
 126
 127         __pContextItem->AddControl(*pButton);
 128         __pContextItem->AddControl(*pButton2);
 129
 130         return r;
 131 }
 132
 133 result
 134 TableViewSample::OnTerminating(void)
 135 {
 136         result r = E_SUCCESS;
 137
 138         // Deallocates the item context
 139         delete __pItemContext;
 140         __pItemContext = null;
 141
 142         return r;
 143 }
 144
 145 // ITableViewItemEventListener implementation
 146 void
 147 TableViewSample::OnTableViewItemStateChanged(TableView& tableView, int itemIndex, TableViewItem* pItem, TableViewItemStatus status)
 148 {
 149         // ....
 150 }
 151
 152 void
 153 TableViewSample::OnTableViewContextItemActivationStateChanged(TableView& tableView, int itemIndex, TableViewContextItem* pContextItem, bool activated)
 154 {
 155         // ....
 156 }
 157
 158 void
 159 TableViewSample::OnTableViewItemReordered(Tizen::Ui::Controls::TableView& tableView, int itemIndexFrom, int itemIndexTo)
 160 {
 161         // ....
 162 }
 163
 164 // ITableViewItemProvider implementation
 165 int
 166 TableViewSample::GetItemCount(void)
 167 {
 168         return 50;
 169 }
 170
 171 int
 172 TableViewSample::GetDefaultItemHeight(void)
 173 {
 174         return 100;
 175 }
 176
 177 TableViewItem*
 178 TableViewSample::CreateItem(int itemIndex, int itemWidth)
 179 {
 180         TableViewAnnexStyle style = TABLE_VIEW_ANNEX_STYLE_NORMAL;
 181         TableViewItem* pItem = new TableViewItem();
 182
 183         switch (itemIndex % 5)
 184         {
 185         case 0:
 186                 style = TABLE_VIEW_ANNEX_STYLE_NORMAL;
 187                 break;
 188         case 1:
 189                 style = TABLE_VIEW_ANNEX_STYLE_MARK;
 190                 break;
 191         case 2:
 192                 style = TABLE_VIEW_ANNEX_STYLE_ONOFF_SLIDING;
 193                 break;
 194         case 3:
 195                 style = TABLE_VIEW_ANNEX_STYLE_DETAILED;
 196                 break;
 197         case 4:
 198                 style = TABLE_VIEW_ANNEX_STYLE_RADIO;
 199                 break;
 200         default:
 201                 break;
 202         }
 203
 204         pItem->Construct(Dimension(itemWidth, GetDefaultItemHeight()), style);
 205
 206         String text;
 207         text.Format(30, L"TableViewItem %d", itemIndex);
 208
 209         Label* pLabel = new Label();
 210         pLabel->Construct(Rectangle(0, 0, itemWidth, GetDefaultItemHeight(), text);
 211
 212         pItem->AddControl(*pLabel);
 213         pItem->SetContextItem(__pContextItem);
 214
 215         return pItem;
 216 }
 217
 218 bool
 219 TableViewSample::DeleteItem(int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem)
 220 {
 221         delete pItem;
 222
 223         return true;
 224 }
 225
 226 void
 227 TableViewSample::UpdateItem(int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem)
 228 {
 229         // ....
 230 }
 231  * @endcode
 232  *
 233  */
 234
 235 class _OSP_EXPORT_ TableView
 236         : public Tizen::Ui::Container
 237 {
 238 public:
 239         /**
 240          * The object is not fully constructed after this constructor is called. Hence, the Construct() method must be called after calling this constructor.
 241          *
 242          * @since 2.0
 243          */
 244         TableView(void);
 245
 246         /**
 247          * This destructor overrides Tizen::Base::Object::~Object().
 248          *
 249          * @since 2.0
 250          */
 251         virtual ~TableView(void);
 252
 253         /**
 254          * Initializes this instance of %TableView with the specified parameters.
 255          *
 256          * @since 2.0
 257          *
 258          * @return  An error code
 259          * @param[in] rect    An instance of the Graphics::Rectangle class
 260          *                              This instance represents the x and y coordinates of the left top corner of the created %TableView along with the width and height.
 261          * @param[in] itemDivider       Set to @c true to display an item divider, @n
 262          *                              else @c false
 263          * @param[in] scrollStyle       The style of %TableView scroll bar style
 264          * @exception E_SUCCESS         The method is successful.
 265          * @exception E_INVALID_ARG     A specified input parameter is invalid, or either the rect.width or rect.height parameter has a negative value.
 266          *
 267          */
 268         result Construct(const Tizen::Graphics::Rectangle& rect, bool itemDivider, TableViewScrollBarStyle scrollStyle);
 269
 270         /**
 271          * Sets the item provider that creates and deletes items for the simple style table view.
 272          *
 273          * @since 2.0
 274          *
 275          * @param[in] pProvider         The item provider to create and delete items
 276          * @remarks If an item provider is not set for the table view, the table view does not work. The specified provider should be allocated in heap memory.
 277          *          To reset the item provider, pass @c null to @c pProvider.
 278          */
 279         void SetItemProvider(ITableViewItemProvider* pProvider);
 280
 281         /**
 282          * Begins the reordering mode.
 283          *
 284          * @since 2.0
 285          *
 286          * @see    ITableViewViewItemEventListener::OnTableViewItemReordered()
 287          */
 288         void BeginReorderingMode(void);
 289
 290         /**
 291          * Ends the reordering mode.
 292          *
 293          * @since 2.0
 294          *
 295          * @see    ITableViewViewItemEventListener::OnTableViewItemReordered()
 296          */
 297         void EndReorderingMode(void);
 298
 299         /**
 300          * Returns whether the %TableView control is in reordering mode or not.
 301          *
 302          * @since 2.0
 303          *
 304          * @return        @c true if the %TableView is in reordering mode, @n
 305          *                   else @c false
 306          */
 307         bool IsInReorderingMode(void) const;
 308
 309         /**
 310          * Adds a listener instance that listens to state changes of table view items. @n
 311          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 312          *
 313          * @since 2.0
 314          *
 315          * @return        An error code
 316          * @param[in] listener               The event listener to add
 317          * @exception E_SUCCESS                                The method is successful.
 318          * @exception E_OBJ_ALREADY_EXIST       The listener is already added.
 319          * @remarks   The specified listener should be allocated in heap memory.
 320          */
 321         result AddTableViewItemEventListener(ITableViewItemEventListener& listener);
 322
 323         /**
 324          * Removes a listener instance that listens to state changes of table view items. @n
 325          * The removed listener cannot listen to events when they are fired.
 326          *
 327          * @since 2.0
 328          *
 329          * @return        An error code
 330          * @param[in] listener     The event listener to remove
 331          * @exception    E_SUCCESS                             The method is successful.
 332          * @exception    E_OBJ_NOT_FOUND        The listener is not found.
 333          */
 334         result RemoveTableViewItemEventListener(ITableViewItemEventListener& listener);
 335
 336         /**
 337          * Adds a listener instance that listens to state changes of a fast scroll. @n
 338          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 339          *
 340          * @since 2.0
 341          *
 342          * @return        An error code
 343          * @param[in] listener     The event listener to add
 344          * @exception    E_SUCCESS                             The method is successful.
 345          * @exception    E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
 346          * @exception    E_OBJ_ALREADY_EXIST The listener is already added.
 347          * @remarks   The specified listener should be allocated in heap memory.
 348          */
 349         result AddFastScrollListener(IFastScrollListener& listener);
 350
 351         /**
 352          * Removes a listener instance that listens to state changes of a fast scroll. @n
 353          * The removed listener cannot listen to events when they are fired.
 354          *
 355          * @since 2.0
 356          *
 357          * @return        An error code
 358          * @param[in] listener     The event listener to remove
 359          * @exception    E_SUCCESS                             The method is successful.
 360          * @exception    E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
 361          * @exception    E_OBJ_NOT_FOUND        The listener is not found.
 362          */
 363         result RemoveFastScrollListener(IFastScrollListener& listener);
 364
 365         /**
 366          * Adds a listener instance that listens to state changes of a scroll event. @n
 367          * The added listener can listen to events on the specified event dispatcher's context when they are fired.
 368          *
 369          * @since 2.0
 370          *
 371          * @return        An error code
 372          * @param[in] listener                          The event listener to add
 373          * @see                 IScrollEventListener::OnScrollEndReached()
 374          * @see                 RemoveScrollEventListener()
 375          * @exception   E_SUCCESS                             The method is successful.
 376          * @exception   E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
 377          * @exception   E_OBJ_ALREADY_EXIST The listener is already added.
 378          * @remarks   The specified listener should be allocated in heap memory.
 379          */
 380         result AddScrollEventListener(IScrollEventListener& listener);
 381
 382         /**
 383          * Removes a listener instance that listens to state changes of a scroll event. @n
 384          * The removed listener cannot listen to events when they are fired.
 385          *
 386          * @since 2.0
 387          *
 388          * @return        An error code
 389          * @param[in] listener     The event listener to remove
 390          * @see  IScrollEventListener::OnScrollEndReached()
 391          * @see           AddScrollEventListener()
 392          * @exception    E_SUCCESS                             The method is successful.
 393          * @exception    E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
 394          * @exception    E_OBJ_NOT_FOUND        The listener is not found.
 395          */
 396         result RemoveScrollEventListener(IScrollEventListener& listener);
 397
 398         /**
 399          * Sets the index table view of the scroll by texts.
 400          *
 401          * @since 2.0
 402          *
 403          * @return        An error code
 404          * @param[in] text                                         The text of the index
 405          * @param[in] useSearchIcon  Set to @c true to show the magnifying icon, @n
 406          *                                                                                   else @c false
 407          * @exception E_SUCCESS                     The method is successful.
 408          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 409          * @exception E_INVALID_OPERATION      The current state of the instance prohibits the execution of the specified operation.
 410          */
 411         result SetFastScrollIndex(const Tizen::Base::String& text, bool useSearchIcon);
 412
 413         /**
 414          * Gets the group and item indexes of the top item.
 415          *
 416          * @since 2.0
 417          *
 418          * @return        The item index
 419          * @exception    E_SUCCESS                   The method is successful.
 420          * @exception    E_OBJ_NOT_FOUND             Top drawn item is not found.
 421          */
 422         int GetTopDrawnItemIndex(void) const;
 423
 424         /**
 425          * Gets the group and item indexes of the bottom item.
 426          *
 427          * @since 2.0
 428          *
 429          * @return        The item index
 430          * @exception    E_SUCCESS                   The method is successful.
 431          * @exception    E_OBJ_NOT_FOUND             Bottom drawn item is not found.
 432          */
 433         int GetBottomDrawnItemIndex(void) const;
 434
 435         /**
 436          * Scrolls to the item at the specified index.
 437          * The specified item is drawn at the position specified by the item alignment.
 438          *
 439          * @since 2.0
 440          *
 441          * @return  An error code
 442          * @param[in] itemIndex             The targeted item index
 443          * @param[in] itemAlignment         The item alignment
 444          * @exception E_SUCCESS             The method is successful.
 445          * @exception E_OUT_OF_RANGE        A specified input parameter is invalid.
 446          */
 447         result ScrollToItem(int itemIndex, TableViewScrollItemAlignment itemAlignment = TABLE_VIEW_SCROLL_ITEM_ALIGNMENT_TOP);
 448
 449         /**
 450          * Checks or unchecks the item at the specified index.
 451          *
 452          * @since 2.0
 453          *
 454          * @return  An error code
 455          * @param[in] itemIndex  The item index to be checked
 456          * @param[in] check    Set to @c true to select the item, @n
 457          *         else @c false
 458          * @exception E_SUCCESS   The method is successful.
 459          * @exception E_OUT_OF_RANGE            A specified input parameter is invalid.
 460          * @exception E_INVALID_OPERATION      The item is disabled.
 461          * @remarks This method works only when the annex style of the item allows selection.
 462          */
 463         result SetItemChecked(int itemIndex, bool check);
 464
 465         /**
 466          * Returns whether the item at the specified index is selected or not.
 467          *
 468          * @since 2.0
 469          *
 470          * @return @c true if the item is selected, @n
 471          *   else @c false
 472          * @param[in] itemIndex  The item itemIndex
 473          * @exception E_SUCCESS                                The method is successful.
 474          * @exception E_OUT_OF_RANGE  A specified input parameter is invalid.
 475          * @remarks This method returns @c false, if the annex style of the item does not allow selection.
 476          */
 477         bool IsItemChecked(int itemIndex) const;
 478
 479         /**
 480          * Enables or disables the item at the specified index.
 481          *
 482          * @since 2.0
 483          *
 484          * @return An error code
 485          * @param[in] itemIndex  The item index
 486          * @param[in] enable    Set to @c true to enable the specified item, @n
 487          *         else @c false
 488          * @exception E_SUCCESS   The method is successful.
 489          * @exception E_OUT_OF_RANGE  A specified input parameter is invalid.
 490          */
 491         result SetItemEnabled(int itemIndex, bool enable);
 492
 493         /**
 494          * Returns whether the item at the specified index is enabled or disabled.
 495          *
 496          * @since 2.0
 497          *
 498          * @return @c true if the item is enabled, @n
 499          *   else @c false
 500          * @param[in] itemIndex  The item index
 501          * @exception E_SUCCESS                                The method is successful.
 502          * @exception E_OUT_OF_RANGE  A specified input parameter is invalid.
 503          */
 504         bool IsItemEnabled(int itemIndex) const;
 505
 506         /**
 507          * Counts all the items of the specified group.
 508          *
 509          * @since 2.0
 510          *
 511          * @return The total number of items
 512          */
 513         int GetItemCount(void) const;
 514
 515         /**
 516          * Updates the specified item. @n
 517          * For instance, TABLE_VIEW_REFRESH_TYPE_ITEM_ADD is used when a new item needs to be added and TABLE_VIEW_REFRESH_TYPE_ITEM_REMOVE is used when an item is deleted from the
 518          * table view. Moreover, TABLE_VIEW_REFRESH_TYPE_ITEM_MODIFY is used when the content of an existing item has changed and it needs to be updated.
 519          * Note that calling this method with TABLE_VIEW_REFRESH_TYPE_ITEM_MODIFY invokes item provider's UpdateItem() for the given index in sequence.
 520          *
 521          * @since 2.0
 522          *
 523          * @return An error code
 524          * @param[in] itemIndex  The item index
 525          * @param[in] type                The item to be added, removed, or modified
 526          * @exception E_SUCCESS   The method is successful.
 527          * @exception E_OUT_OF_RANGE  A specified input parameter is invalid.
 528          * @remarks If the specified itemIndex.
 529          */
 530         result RefreshItem(int itemIndex, TableViewRefreshType type);
 531
 532         /**
 533          * Updates all the items of a table view.
 534          *
 535          * @since 2.0
 536          *
 537          * @return An error code
 538          * @remarks This method clears all the items in the table view and invokes the methods of the item provider again to update the table view.
 539          */
 540         void UpdateTableView(void);
 541
 542         /**
 543          * Gets the index of the item at the specified position.
 544          *
 545          * @since 2.0
 546          *
 547          * @return  The item index of the item on specified position
 548          * @param[in] position   The position of the item
 549          * @remarks This method returns -1 if no item is found at the given position.
 550          */
 551         int GetItemIndexFromPosition(const Tizen::Graphics::Point& position) const;
 552
 553         /**
 554          * Sets the color of a division line between items.
 555          *
 556          * @since 2.0
 557          *
 558          * @return An error code
 559          * @param[in] color    The division line color
 560          */
 561         void SetItemDividerColor(const Tizen::Graphics::Color& color);
 562
 563         /**
 564          * Gets the color of a division line between items.
 565          *
 566          * @since 2.0
 567          *
 568          * @return        The color of a division line
 569          */
 570         Tizen::Graphics::Color GetItemDividerColor(void) const;
 571
 572         /**
 573          * Sets the background color of this control.
 574          *
 575          * @since 2.0
 576          *
 577          * @param[in] color          The background color
 578          * @remarks The background bitmap has priority over the background color. When both the background bitmap and the background color are specified,
 579          *        only the bitmap image is displayed.
 580          */
 581         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 582
 583         /**
 584          * Gets the background color of this control.
 585          *
 586          * @since 2.0
 587          *
 588          * @return The background color
 589          */
 590         Tizen::Graphics::Color GetBackgroundColor(void) const;
 591
 592         /**
 593          * Sets the scroll input handling mode.
 594          *
 595          * @since 2.0
 596          *
 597          * @param[in] mode  The scroll input handling mode
 598          * @see         GetScrollInputMode()
 599          */
 600         void SetScrollInputMode(ScrollInputMode mode);
 601
 602
 603         /**
 604          * Gets the scroll input handling mode.
 605          *
 606          * @since 2.0
 607          *
 608          * @return     The scroll input handling mode
 609          * @see         SetScrollInputMode()
 610          */
 611         ScrollInputMode GetScrollInputMode(void) const;
 612
 613         /*
 614          * Scrolls the list contents with the amount of pixels.
 615          *
 616          * @since 2.0
 617          *
 618          * @return  An error code
 619          * @param[in]   pixel                                    The amount of pixels to scroll
 620          * @exception   E_SUCCESS                        The method is successful.
 621          * @exception   E_OUT_OF_RANGE   The specified @c pixel is out of range.
 622          * @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.
 623          *                         Likewise, in case of positive @c pixel on the bottom position of scroll it will also return E_OUT_OF_RANGE.
 624          */
 625         result ScrollByPixel(int pixel);
 626
 627         /*
 628          * Gets the current scroll position
 629          *
 630          * @since 2.0
 631          */
 632          int GetCurrentScrollPosition(void) const;
 633
 634         /*
 635          * Enables or disables the scroll of TableView items.
 636          *
 637          * @since 2.0
 638          */
 639         void SetScrollEnabled(bool enable);
 640
 641         /*
 642          * Checks whether the scroll is enabled or disabled.
 643          *
 644          * @since 2.0
 645          */
 646         bool IsScrollEnabled(void) const;
 647
 648 private:
 649         friend class _TableViewImpl;
 650
 651         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 652         TableView(const TableView& rhs);
 653
 654         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 655         TableView& operator =(const TableView& rhs);
 656 }; // TableView
 657
 658 }}} // Tizen::Ui::Controls
 659
 660 #endif  // _FUI_CTRL_TABLE_VIEW_H_