2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://floralicense.org/license/
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.
19 * @file FUiCtrlSectionTableView.h
20 * @brief This is the header file for the %SectionTableView class.
22 * This header file contains the declarations of the %SectionTableView class and its helper classes.
25 #ifndef _FUI_CTRL_SECTION_TABLE_VIEW_H_
26 #define _FUI_CTRL_SECTION_TABLE_VIEW_H_
28 #include <FGrpRectangle.h>
29 #include <FGrpColor.h>
30 #include <FUiContainer.h>
31 #include <FUiCtrlTableViewTypes.h>
33 namespace Tizen { namespace Ui { namespace Controls
35 class ISectionTableViewItemProvider;
36 class ISectionTableViewItemEventListener;
37 class IFastScrollListener;
38 class IScrollEventListener;
41 * @class SectionTableView
42 * @brief This class defines common behavior for a %SectionTableView control.
46 * The %SectionTableView class defines common behavior for a %SectionTableView control.
48 //Sample code for SectionTableViewSample.h
51 class SectionTableViewSample
52 : public Tizen::Ui::Controls::Form
53 , public Tizen::Ui::Controls::ISectionTableViewItemProvider
54 , public Tizen::Ui::Controls::ISectionTableViewItemEventListener
57 SectionTableViewSample(void)
58 : __pSectionTableView(null)
59 , __pContextItem(null){}
61 bool Initialize(void);
62 virtual result OnInitializing(void);
63 virtual result OnTerminating(void);
65 // ISectionTableViewItemEventListener
66 virtual void OnSectionTableViewItemStateChanged(Tizen::Ui::Controls::SectionTableView& tableView, int sectionIndex, int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem, Tizen::Ui::Controls::TableViewItemStatus status);
67 virtual void OnSectionTableViewContextItemActivationStateChanged(Tizen::Ui::Controls::SectionTableView& tableView, int sectionIndex, int itemIndex, Tizen::Ui::Controls::TableViewContextItem* pContextItem, bool activated);
69 // ISectionTableViewItemProvider
70 virtual int GetSectionCount(void);
71 virtual int GetItemCount(int sectionIndex);
72 virtual bool HasSectionHeader(int sectionIndex);
73 virtual bool HasSectionFooter(int sectionIndex);
74 virtual Tizen::Base::String GetSectionHeader(int sectionIndex);
75 virtual Tizen::Base::String GetSectionFooter(int sectionIndex);
76 virtual int GetDefaultItemHeight(void);
77 virtual Tizen::Ui::Controls::TableViewItem* CreateItem(int sectionIndex, int itemIndex, int itemWidth);
78 virtual bool DeleteItem(int sectionIndex, int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem);
79 virtual void UpdateItem(int sectionIndex, int itemIndex, Tizen::Ui::Controls::TableViewItem* pItem);
82 Tizen::Ui::Controls::SectionTableView* __pSectionTableView;
88 //Sample code for SectionTableViewSample.cpp
90 #include <FGraphics.h>
92 #include "SectionTableViewSample.h"
94 using namespace Tizen::App;
95 using namespace Tizen::Base;
96 using namespace Tizen::Graphics;
97 using namespace Tizen::Media;
98 using namespace Tizen::Ui::Controls;
101 SectionTableViewSample::Initialize(void)
103 Construct(FORM_STYLE_NORMAL);
108 SectionTableViewSample::OnInitializing(void)
110 result r = E_SUCCESS;
112 // Creates an instance of TableView
113 __pSectionTableView = new TableView();
114 __pSectionTableView->Construct(Rectangle(0, 0, GetClientAreaBounds().width, GetClientAreaBounds().height), true, TABLE_VIEW_SCROLL_BAR_STYLE_FADE_OUT);
115 __pSectionTableView->SetItemProvider(*this);
116 __pSectionTableView->AddTableViewItemEventListener(*this);
118 // Adds the TableView to the form
119 AddControl(*__pSectionTableView);
124 SectionTableViewSample::OnTerminating(void)
129 // ISectionTableViewItemEventListener implementation
131 SectionTableViewSample::OnSectionTableViewItemStateChanged(SectionTableView& tableView, int sectionIndex, int itemIndex, TableViewItem* pItem, TableViewItemStatus status)
137 SectionTableViewSample::OnSectionTableViewContextItemActivationStateChanged(SectionTableView& tableView, int sectionIndex, int itemIndex, TableViewContextItem* pContextItem, bool activated)
142 // ISectionTableViewItemProvider implementation
144 SectionTableViewSample::GetSectionCount(void)
150 SectionTableViewSample::GetItemCount(int sectionIndex)
156 SectionTableViewSample::HasSectionHeader(int sectionIndex)
162 SectionTableViewSample::HasSectionFooter(int sectionIndex)
168 SectionTableViewSample::GetSectionHeader(int sectionIndex)
171 text.Format(30, L"Section header %d", sectionIndex);
177 SectionTableViewSample::GetSectionFooter(int sectionIndex)
180 text.Format(30, L"Section footer %d", sectionIndex);
186 SectionTableViewSample::GetDefaultItemHeight(void)
192 SectionTableViewSample::CreateItem(int sectionIndex, int itemIndex, int itemWidth)
194 TableViewAnnexStyle style = TABLE_VIEW_ANNEX_STYLE_NORMAL;
195 TableViewItem* pItem = new TableViewItem();
197 switch (itemIndex % 5)
200 style = TABLE_VIEW_ANNEX_STYLE_NORMAL;
203 style = TABLE_VIEW_ANNEX_STYLE_MARK;
206 style = TABLE_VIEW_ANNEX_STYLE_ONOFF_SLIDING;
209 style = TABLE_VIEW_ANNEX_STYLE_DETAILED;
212 style = TABLE_VIEW_ANNEX_STYLE_RADIO;
218 pItem->Construct(Dimension(itemWidth, GetDefaultItemHeight()), style);
221 text.Format(30, L"TableViewItem %d", itemIndex);
223 Label* pLabel = new Label();
224 pLabel->Construct(Rectangle(0, 0, itemWidth, GetDefaultItemHeight(), text);
226 pItem->AddControl(*pLabel);
233 SectionTableViewSample::DeleteItem(int sectionIndex, int itemIndex, TableViewItem* pItem)
241 SectionTableViewSample::UpdateItem(int sectionIndex, int itemIndex, TableViewItem* pItem)
249 class _OSP_EXPORT_ SectionTableView
250 : public Tizen::Ui::Container
254 * The object is not fully constructed after this constructor is called. Hence, the Construct() method must be called after calling this constructor.
258 SectionTableView(void);
261 * This destructor overrides Tizen::Base::Object::~Object().
265 virtual ~SectionTableView(void);
268 * Initializes this instance of %SectionTableView with the specified parameters.
272 * @return An error code
273 * @param[in] rect An instance of the Graphics::Rectangle class
274 * This instance represents the x and y coordinates of the left top corner of the created %SectionTableView along with the width and height.
275 * @param[in] itemDivider Set to @c true to display an item divider, @n
277 * @param[in] scrollStyle The style of %SectionTableView scroll bar style
278 * @exception E_SUCCESS The method is successful.
279 * @exception E_INVALID_ARG A specified input parameter is invalid, or either the rect.width or rect.height parameter has a negative value.
282 result Construct(const Tizen::Graphics::Rectangle& rect, bool itemDivider, TableViewScrollBarStyle scrollStyle);
285 * Sets the item provider that creates and deletes items for the section style table view.
289 * @param[in] pProvider The item provider to create and delete items
290 * @remarks If an item provider is not set for the table view, the table view does not work.
291 * The specified provider should be allocated in heap memory.
293 void SetItemProvider(ISectionTableViewItemProvider* pProvider);
296 * Sets the color of a section.
300 * @param[in] color The section color
301 * @remarks This method works only when the style of the %SectionTableView control is TABLE_VIEW_STYLE_SECTION.
303 void SetSectionColor(const Tizen::Graphics::Color& color);
306 * Gets the color of a section.
310 * @return The section color
312 Tizen::Graphics::Color GetSectionColor(void) const;
315 * Sets the grouped look is enabled.
319 * @param[in] enable The enabled/disabled status
321 void SetGroupedLookEnabled(bool enable);
324 * Returns whether the grouped look is enabled or not.
328 * @return @c true if the grouped look is enabled, else @c false
330 bool IsGroupedLookEnabled(void) const;
333 * Adds a listener instance that listens to state changes of table view items. @n
334 * The added listener can listen to events on the specified event dispatcher's context when they are fired.
338 * @return An error code
339 * @param[in] listener The event listener to add
340 * @exception E_SUCCESS The method is successful.
341 * @exception E_OBJ_ALREADY_EXIST The listener is already added.
342 * @remarks The specified listener should be allocated in heap memory.
344 result AddSectionTableViewItemEventListener(ISectionTableViewItemEventListener& listener);
347 * Removes a listener instance that listens to state changes of table view items. @n
348 * The removed listener cannot listen to events when they are fired.
352 * @return An error code
353 * @param[in] listener The event listener to remove
354 * @exception E_SUCCESS The method is successful.
355 * @exception E_OBJ_NOT_FOUND The listener is not found.
357 result RemoveSectionTableViewItemEventListener(ISectionTableViewItemEventListener& listener);
360 * Adds a listener instance that listens to state changes of a fast scroll. @n
361 * The added listener can listen to events on the specified event dispatcher's context when they are fired.
365 * @return An error code
366 * @param[in] listener The event listener to add
367 * @exception E_SUCCESS The method is successful.
368 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
369 * @exception E_OBJ_ALREADY_EXIST The listener is already added.
370 * @remarks The specified listener should be allocated in heap memory.
372 result AddFastScrollListener(IFastScrollListener& listener);
375 * Removes a listener instance that listens to state changes of a fast scroll. @n
376 * The removed listener cannot listen to events when they are fired.
380 * @return An error code
381 * @param[in] listener The event listener to remove
382 * @exception E_SUCCESS The method is successful.
383 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
384 * @exception E_OBJ_NOT_FOUND The listener is not found.
386 result RemoveFastScrollListener(IFastScrollListener& listener);
389 * Adds a listener instance that listens to state changes of a scroll event. @n
390 * The added listener can listen to events on the specified event dispatcher's context when they are fired.
394 * @return An error code
395 * @param[in] listener The event listener to add
396 * @see IScrollEventListener::OnScrollEndReached()
397 * @see RemoveScrollEventListener()
398 * @exception E_SUCCESS The method is successful.
399 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
400 * @exception E_OBJ_ALREADY_EXIST The listener is already added.
401 * @remarks The specified listener should be allocated in heap memory.
403 result AddScrollEventListener(IScrollEventListener& listener);
406 * Removes a listener instance that listens to state changes of a scroll event. @n
407 * The removed listener cannot listen to events when they are fired.
411 * @return An error code
412 * @param[in] listener The event listener to remove
413 * @see IScrollEventListener::OnScrollEndReached()
414 * @see AddScrollEventListener()
415 * @exception E_SUCCESS The method is successful.
416 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
417 * @exception E_OBJ_NOT_FOUND The listener is not found.
419 result RemoveScrollEventListener(IScrollEventListener& listener);
422 * Sets the text index of the fast scroll.
426 * @return An error code
427 * @param[in] text The text of the index
428 * @param[in] useSearchIcon Set to @c true to show the magnifying icon, @n
430 * @exception E_SUCCESS The method is successful.
431 * @exception E_INVALID_ARG A specified input parameter is invalid.
432 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
434 result SetFastScrollIndex(const Tizen::Base::String& text, bool useSearchIcon);
437 * Gets the section and item indexes of the top item.
441 * @return An error code
442 * @param[out] sectionIndex The section index
443 * @param[out] itemIndex The item index
444 * @exception E_SUCCESS The method is successful.
445 * @exception E_OBJ_NOT_FOUND Top drawn item is not found.
447 result GetTopDrawnItemIndex(int& sectionIndex, int& itemIndex) const;
450 * Gets the section and item indexes of the bottom item.
454 * @return An error code
455 * @param[out] sectionIndex The section index
456 * @param[out] itemIndex The item index
457 * @exception E_SUCCESS The method is successful.
458 * @exception E_OBJ_NOT_FOUND Bottom drawn item is not found.
460 result GetBottomDrawnItemIndex(int& sectionIndex, int& itemIndex) const;
463 * Scrolls to the item at the specified index.
464 * The specified item is drawn at the position specified by the item alignment.
468 * @return An error code
469 * @param[in] sectionIndex The section index
470 * @param[in] itemIndex The item index
471 * @param[in] itemAlignment The item alignment
472 * @exception E_SUCCESS The method is successful.
473 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
475 result ScrollToItem(int sectionIndex, int itemIndex, TableViewScrollItemAlignment itemAlignment = TABLE_VIEW_SCROLL_ITEM_ALIGNMENT_TOP);
478 * Checks or unchecks the item at the specified index.
482 * @return An error code
483 * @param[in] sectionIndex The section index
484 * @param[in] itemIndex The item index
485 * @param[in] check Set to @c true to select the item, @n
487 * @exception E_SUCCESS The method is successful.
488 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
489 * @exception E_INVALID_OPERATION The item is disabled.
490 * @remarks This method works only when the annex style of the item allows selection.
492 result SetItemChecked(int sectionIndex, int itemIndex, bool check);
495 * Returns whether the item at the specified index is selected or not.
499 * @return @c true if the item is selected, @n
501 * @param[in] sectionIndex The section index
502 * @param[in] itemIndex The item index
503 * @exception E_SUCCESS The method is successful.
504 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
505 * @remarks This method returns @c false, if the annex style of the item does not allow selection.
507 bool IsItemChecked(int sectionIndex, int itemIndex) const;
510 * Enables or disables the item at the specified index.
514 * @return An error code
515 * @param[in] sectionIndex The section index
516 * @param[in] itemIndex The item index
517 * @param[in] enable Set to @c true to enable the specified item, @n
519 * @exception E_SUCCESS The method is successful.
520 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
522 result SetItemEnabled(int sectionIndex, int itemIndex, bool enable);
525 * Returns whether the item at the specified index is enabled or disabled.
529 * @return @c true if the item is enabled, @n
531 * @param[in] sectionIndex The section index
532 * @param[in] itemIndex The item index
533 * @exception E_SUCCESS The method is successful.
534 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
536 bool IsItemEnabled(int sectionIndex, int itemIndex) const;
539 * Counts the total number of sections.
543 * @return The total number of sections
545 int GetSectionCount(void) const;
548 * Counts all the items of the specified section.
552 * @return The total number of items in the specified section
553 * @param[in] sectionIndex The section index
554 * @exception E_SUCCESS The method is successful.
555 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
557 int GetItemCountAt(int sectionIndex) const;
560 * Updates the specified item. @n
561 * 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
562 * 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.
563 * Note that calling this method with TABLE_VIEW_REFRESH_TYPE_ITEM_MODIFY invokes item provider's UpdateItem() for the given index in sequence.
567 * @return An error code
568 * @param[in] sectionIndex The section index
569 * @param[in] itemIndex The item index
570 * @param[in] type The item to be added, removed, or modified
571 * @exception E_SUCCESS The method is successful.
572 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
573 * @remarks If the specified item. itemIndex is -1, then the method is applied to the section item with the given index.
574 * Note that if TABLE_VIEW_REFRESH_TYPE_ITEM_REMOVE option is used to a section item, all the items in the section (including the section item itself) are
575 * removed from the table view.
577 result RefreshItem(int sectionIndex, int itemIndex, TableViewRefreshType type);
580 * Updates all the items of a table view.
584 * @return An error code
585 * @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.
587 void UpdateTableView(void);
590 * Gets the index of the item at the specified position.
594 * @param[in] position The position of the item
595 * @param[out] sectionIndex The section index of the item on specified position
596 * @param[out] itemIndex The item index of the item on specified position
597 * @remarks This method sets both of sectionIndex and itemIndex to -1 if no item is found at the given position.
599 result GetItemIndexFromPosition(const Tizen::Graphics::Point& position, int& sectionIndex, int& itemIndex) const;
602 * Sets the color of a division line between items.
606 * @return An error code
607 * @param[in] color The division line color
609 void SetItemDividerColor(const Tizen::Graphics::Color& color);
612 * Gets the color of a division line between items.
616 * @return The color of a division line
618 Tizen::Graphics::Color GetItemDividerColor(void) const;
621 * Sets the background color of this control.
625 * @param[in] color The background color
626 * @remarks The background bitmap has priority over the background color. When both the background bitmap and the background color are specified,
627 * only the bitmap image is displayed.
629 void SetBackgroundColor(const Tizen::Graphics::Color& color);
632 * Gets the background color of this control.
636 * @return The background color
638 Tizen::Graphics::Color GetBackgroundColor(void) const;
641 * Sets the scroll input handling mode.
645 * @param[in] mode The scroll input handling mode
646 * @see GetScrollInputMode()
648 void SetScrollInputMode(ScrollInputMode mode);
651 * Gets the scroll input handling mode.
655 * @return The scroll input handling mode
656 * @see SetScrollInputMode()
658 ScrollInputMode GetScrollInputMode(void) const;
661 * Scrolls the list contents with the amount of pixels.
665 * @return An error code
666 * @param[in] pixel The amount of pixels to scroll
667 * @exception E_SUCCESS The method is successful.
668 * @exception E_OUT_OF_RANGE The specified @c pixel is out of range.
669 * @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.
670 * Likewise, in case of positive @c pixel on the bottom position of scroll it will also return E_OUT_OF_RANGE.
672 result ScrollByPixel(int pixel);
675 * Gets the current scroll position
679 int GetCurrentScrollPosition(void) const;
682 * Enables or disables the scroll of SectionTableView items.
686 void SetScrollEnabled(bool enable);
689 * Checks whether the scroll is enabled or disabled.
693 bool IsScrollEnabled(void) const;
696 friend class _TableViewImpl;
698 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
699 SectionTableView(const SectionTableView& rhs);
701 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
702 SectionTableView& operator =(const SectionTableView& rhs);
703 }; // SectionTableView
705 }}} // Tizen::Ui::Controls
707 #endif // _FUI_CTRL_SECTION_TABLE_VIEW_H_