2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0/
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 FUiCtrlGroupedListView.h
20 * @brief This is the header file for the %GroupedListView class.
22 * This header file contains the declarations of the %GroupedListView class and its helper classes.
25 #ifndef _FUI_CTRL_GROUPED_LIST_VIEW_H_
26 #define _FUI_CTRL_GROUPED_LIST_VIEW_H_
28 #include <FBaseObject.h>
29 #include <FBaseTypes.h>
30 #include <FGrpFloatRectangle.h>
31 #include <FGrpRectangle.h>
32 #include <FUiControl.h>
33 #include <FUiContainer.h>
34 #include <FUiCtrlGroupedListViewTypes.h>
35 #include <FUiCtrlIFastScrollListener.h>
36 #include <FUiCtrlIGroupedListViewItemEventListener.h>
37 #include <FUiCtrlIGroupedListViewItemProvider.h>
38 #include <FUiCtrlIGroupedListViewItemProviderF.h>
39 #include <FUiCtrlIScrollEventListener.h>
40 #include <FUiCtrlIScrollEventListenerF.h>
41 #include <FUiCtrlListViewTypes.h>
42 #include <FUiCtrlScrollPanelTypes.h>
43 #include <FUiIUiLinkEventListener.h>
45 namespace Tizen { namespace Ui { namespace Controls
48 class _GroupedListViewImpl;
51 * @class GroupedListView
52 * @brief This class defines the common behavior of a %GroupedListView control.
56 * The %GroupedListView class displays a list of grouped items in a list. The items in a GroupedList control consist of groups and
57 * items. A group represents the grouped items and is placed at the first level. Each group consists of simple or custom items.
58 * Therefore, items are uniquely identified with two indexes: group index and item index.
60 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_listviews.htm">ListViews</a>.
62 * The following example demonstrates how to use the %GroupedListView class.
66 //Sample code for GroupedListViewSample.h
70 class CustomGroupedListElement;
72 class GroupedListViewSample
73 : public Tizen::Ui::Controls::Form
74 , public Tizen::Ui::Controls::IGroupedListViewItemEventListener
75 , public Tizen::Ui::Controls::IGroupedListViewItemProvider
78 GroupedListViewSample(void)
79 : __pGroupedListView(null)
80 , __pCustomGroupedListElement(null){}
82 bool Initialize(void);
83 virtual result OnInitializing(void);
84 virtual result OnTerminating(void);
86 // IGroupedListViewItemEventListener
87 virtual void OnGroupedListViewContextItemStateChanged(Tizen::Ui::Controls::GroupedListView &listView, int groupIndex, int itemIndex, int elementId, Tizen::Ui::Controls::ListContextItemStatus state);
88 virtual void OnGroupedListViewItemStateChanged(Tizen::Ui::Controls::GroupedListView &listView, int groupIndex, int itemIndex, int elementId, Tizen::Ui::Controls::ListItemStatus state);
89 virtual void OnGroupedListViewItemSwept(Tizen::Ui::Controls::GroupedListView &listView, int groupIndex, int itemIndex, Tizen::Ui::Controls::SweepDirection direction);
91 // IGroupedListViewItemProvider
92 virtual int GetGroupCount(void);
93 virtual int GetItemCount(int groupIndex);
94 virtual Tizen::Ui::Controls::ListItemBase* CreateItem(int groupIndex, int itemIndex, int itemWidth);
95 virtual Tizen::Ui::Controls::GroupItem* CreateGroupItem(int groupIndex, int itemWidth);
96 virtual bool DeleteItem(int groupIndex, int itemIndex, Tizen::Ui::Controls::ListItemBase* pItem, int itemWidth);
97 virtual bool DeleteGroupItem(int groupIndex, Tizen::Ui::Controls::GroupItem* pItem, int itemWidth);
100 static const int ID_FORMAT_STRING = 100;
101 static const int ID_FORMAT_BITMAP = 101;
102 static const int ID_FORMAT_CUSTOM = 102;
103 static const int ID_CONTEXT_ITEM_1 = 103;
104 static const int ID_CONTEXT_ITEM_2 = 104;
106 Tizen::Graphics::Bitmap* __pHome;
107 Tizen::Graphics::Bitmap* __pMsg;
108 Tizen::Graphics::Bitmap* __pAlarm;
109 Tizen::Graphics::Bitmap* __pCall;
111 Tizen::Ui::Controls::GroupedListView* __pGroupedListView;
112 Tizen::Ui::Controls::ListContextItem* __pItemContext;
113 CustomGroupedListElement* __pCustomGroupedListElement;
118 //Sample code for GroupedListViewSample.cpp
120 #include <FGraphics.h>
122 #include "GroupedListViewSample.h"
124 using namespace Tizen::App;
125 using namespace Tizen::Base;
126 using namespace Tizen::Graphics;
127 using namespace Tizen::Ui::Controls;
129 class CustomGroupedListElement
130 : public ICustomElement
134 OnDraw(Canvas& canvas, const Rectangle& rect, ListItemDrawingStatus itemStatus)
136 Tizen::Graphics::Font font;
137 font.Construct(FONT_STYLE_PLAIN, 15);
138 canvas.SetFont(font);
139 canvas.SetLineWidth(3);
140 canvas.SetForegroundColor(Color::GetColor(COLOR_ID_GREEN));
142 if (canvas.DrawRectangle(rect) != E_SUCCESS)
147 if (canvas.DrawText(Point(rect.x+10, rect.y+15), L"Custom") != E_SUCCESS)
157 GroupedListViewSample::Initialize(void)
159 Construct(FORM_STYLE_NORMAL);
164 GroupedListViewSample::OnInitializing(void)
166 result r = E_SUCCESS;
168 // Creates an instance of IconListView
169 __pGroupedListView = new GroupedListView();
170 __pGroupedListView->Construct(Rectangle(0, 0, GetClientAreaBounds().width, GetClientAreaBounds().height), GROUPED_LIST_VIEW_STYLE_INDEXED, true, true);
171 __pGroupedListView->SetItemProvider(*this);
172 __pGroupedListView->AddGroupedListViewItemEventListener(*this);
174 // Adds the icon list view to the form
175 AddControl(__pGroupedListView);
177 // Creates an instance of ListContextItem
178 __pItemContext = new ListContextItem();
179 __pItemContext->Construct();
180 __pItemContext->AddElement(ID_CONTEXT_ITEM_1, "Test1");
181 __pItemContext->AddElement(ID_CONTEXT_ITEM_2, "Test2");
183 // Gets instances of Bitmap
184 AppResource* pAppResource = Application::GetInstance()->GetAppResource();
185 __pHome = pAppResource->GetBitmapN(L"tizen.png");
186 __pMsg = pAppResource->GetBitmapN(L"tizen.png");
187 __pAlarm = pAppResource->GetBitmapN(L"tizen.png");
188 __pCall = pAppResource->GetBitmapN(L"tizen.png");
190 // Creates an instance of CustomGroupedListElement
191 __pCustomGroupedListElement = new CustomGroupedListElement();
197 GroupedListViewSample::OnTerminating(void)
199 result r = E_SUCCESS;
201 // Deallocates bitmaps
207 // Deallocates the item context
208 delete __pItemContext;
214 GroupedListViewSample::OnGroupedListViewItemStateChanged(GroupedListView &listView, int groupIndex, int itemIndex, int elementId, ListItemStatus state)
218 case ID_FORMAT_STRING:
223 case ID_FORMAT_BITMAP:
234 GroupedListViewSample::OnGroupedListViewContextItemStateChanged(GroupedListView &listView, int groupIndex, int itemIndex, int elementId, ListContextItemStatus state)
238 case ID_CONTEXT_ITEM_1:
243 case ID_CONTEXT_ITEM_2:
253 // IGroupedListViewItemEventListener
255 GroupedListViewSample::OnGroupedListViewItemSwept(GroupedListView &listView, int groupIndex, int itemIndex, SweepDirection direction)
261 GroupedListViewSample::GetGroupCount(void)
267 GroupedListViewSample::GetItemCount(int groupIndex)
294 // IGroupedListViewItemProvider
296 GroupedListViewSample::CreateGroupItem(int groupIndex, int itemWidth)
298 String text("Group ");
299 text.Append(groupIndex+1);
301 GroupItem* pItem = new GroupItem();
302 pItem->Construct(Dimension(itemWidth, 40));
303 pItem->SetElement(text, null);
309 GroupedListViewSample::CreateItem(int groupIndex, int itemIndex, int itemWidth)
311 // Creates an instance of CustomItem
312 CustomItem* pItem = new CustomItem();
313 ListAnnexStyle style = LIST_ANNEX_STYLE_NORMAL;
314 pItem->Construct(Dimension(itemWidth, 100), style);
316 switch (itemIndex % 4)
320 style = LIST_ANNEX_STYLE_NORMAL;
321 pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pHome, null, null);
322 pItem->AddElement(Rectangle(150, 25, 150, 50), ID_FORMAT_STRING, L"Home", true);
327 style = LIST_ANNEX_STYLE_MARK;
328 pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pMsg, null, null);
329 pItem->AddElement(Rectangle(150, 25, 150, 50), ID_FORMAT_STRING, L"Msg", true);
334 style = LIST_ANNEX_STYLE_ONOFF_SLIDING;
335 pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pAlarm, null, null);
336 pItem->AddElement(Rectangle(150, 25, 150, 50), ID_FORMAT_STRING, L"Alarm", true);
341 style = LIST_ANNEX_STYLE_DETAILED;
342 pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pCall, null, null);
343 pItem->AddElement(Rectangle(150, 25, 150, 50), ID_FORMAT_STRING, L"Call", true);
349 pItem->AddElement(Rectangle(360, 10, 180, 80), ID_FORMAT_CUSTOM, *(static_cast<ICustomElement *>(__pCustomGroupedListElement)));
350 pItem->SetContextItem(__pItemContext);
356 GroupedListViewSample::DeleteItem(int groupIndex, int itemIndex, ListItemBase* pItem, int itemWidth)
364 GroupedListViewSample::DeleteGroupItem(int groupIndex, GroupItem* pItem, int itemWidth)
375 class _OSP_EXPORT_ GroupedListView
376 : public Tizen::Ui::Control
380 * The object is not fully constructed after this constructor is
381 * called. @n For full construction, the %Construct() method must be
382 * called right after calling this constructor.
386 GroupedListView(void);
389 * This destructor overrides Tizen::Base::Object::~Object().
393 virtual ~GroupedListView(void);
397 * Initializes this instance of %GroupedListView with the specified parameters.
399 * @brief <i> [Deprecated] </i>
400 * @deprecated This method is deprecated.
403 * @return An error code
404 * @param[in] rect An instance of the Graphics::Rectangle class
405 * This instance represents the x and y coordinates of the top-left corner of the created
406 * %GroupedListView control along with the width and height.@n
407 * The optimal size of the control is defined in
408 * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
409 * @param[in] style The style of the %GroupedListView control
410 * @param[in] itemDivider Set to @c true to display an item divider, @n
412 * @param[in] fastScroll Set to @c true to use the fast scroll, @n
414 * @exception E_SUCCESS The method is successful.
415 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
416 * Either the @c rect.width or @c rect.height parameter has a negative value.
417 * @exception E_SYSTEM A system error has occurred.
420 result Construct(const Tizen::Graphics::Rectangle& rect, GroupedListViewStyle style, bool itemDivider = true, bool fastScroll = false);
423 * Initializes this instance of %GroupedListView with the specified parameters.
427 * @return An error code
428 * @param[in] rect An instance of the Graphics::Rectangle class
429 * This instance represents the x and y coordinates of the top-left corner of the created
430 * %GroupedListView control along with the width and height.@n
431 * The optimal size of the control is defined in
432 * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
433 * @param[in] style The style of the %GroupedListView control
434 * @param[in] itemDivider Set to @c true to display an item divider, @n
436 * @param[in] scrollStyle Set to scroll style
437 * @exception E_SUCCESS The method is successful.
438 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
439 * Either the @c rect.width or @c rect.height parameter has a negative value.
440 * @exception E_SYSTEM A system error has occurred.
442 result Construct(const Tizen::Graphics::Rectangle& rect, GroupedListViewStyle style, bool itemDivider, ListScrollStyle scrollStyle);
445 * Initializes this instance of %GroupedListView with the specified parameters.
449 * @return An error code
450 * @param[in] rect An instance of the Graphics::Rectangle class
451 * This instance represents the x and y coordinates of the top-left corner of the created
452 * %GroupedListView control along with the width and height.@n
453 * The optimal size of the control is defined in
454 * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
455 * @param[in] style The style of the %GroupedListView control
456 * @param[in] itemDivider Set to @c true to display an item divider, @n
458 * @param[in] scrollStyle Set to scroll style
459 * @exception E_SUCCESS The method is successful.
460 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
461 * Either the @c rect.width or @c rect.height parameter has a negative value.
462 * @exception E_SYSTEM A system error has occurred.
464 result Construct(const Tizen::Graphics::FloatRectangle& rect, GroupedListViewStyle style, bool itemDivider, ListScrollStyle scrollStyle);
467 * Sets the item provider that creates and deletes items from the list.
471 * @return An error code
472 * @param[in] provider The item provider to create and delete items
473 * @exception E_SUCCESS The method is successful.
474 * @exception E_SYSTEM A system error has occurred.
476 * - If an item provider is not set for the list, the list does not work.
477 * - A provider should be allocated on a heap memory.
479 result SetItemProvider(IGroupedListViewItemProvider& provider);
482 * Sets the item provider that creates and deletes items from the list.
486 * @return An error code
487 * @param[in] provider The item provider to create and delete items
488 * @exception E_SUCCESS The method is successful.
489 * @exception E_SYSTEM A system error has occurred.
490 * @remarks If an item provider is not set for the list, the list does not work. @n
491 * A provider should be allocated on a heap memory.
493 result SetItemProvider(IGroupedListViewItemProviderF& provider);
496 * Adds an IGroupedListViewItemEventListener instance that listens to the state changes of the list view items. @n
497 * The added listener can listen to events on the specified event dispatcher's context when they are fired.
501 * @param[in] listener The event listener to add
503 void AddGroupedListViewItemEventListener(IGroupedListViewItemEventListener& listener);
506 * Removes an IGroupedListViewItemEventListener instance that listens to the state changes of the list view items. @n
507 * The removed listener cannot listen to events when they are fired.
511 * @param[in] listener The event listener to remove
513 void RemoveGroupedListViewItemEventListener(IGroupedListViewItemEventListener& listener);
516 * Adds an IFastScrollListener instance that listens to the state changes of a fast scroll. @n
517 * The added listener can listen to events on the specified event dispatcher's context when they are fired.
521 * @param[in] listener The event listener to add
523 void AddFastScrollListener(IFastScrollListener& listener);
526 * Removes an IFastScrollListener instance that listens to the state changes of a fast scroll. @n
527 * The removed listener cannot listen to events when they are fired.
531 * @param[in] listener The event listener to remove
533 void RemoveFastScrollListener(IFastScrollListener& listener);
536 * Adds an IScrollEventListener instance that listens to the state changes of a scroll event. @n
537 * The added listener can listen to events on the specified event dispatcher's context when they are fired.
541 * @param[in] listener The event listener to add
542 * @see IScrollEventListener::OnScrollEndReached()
543 * @see RemoveScrollEventListener()
545 void AddScrollEventListener(IScrollEventListener& listener);
548 * Adds an IScrollEventListener instance that listens to the state changes of a scroll event. @n
549 * The added listener can listen to events on the specified event dispatcher's context when they are fired.
553 * @param[in] listener The event listener to add
554 * @see IScrollEventListener::OnScrollEndReached()
555 * @see RemoveScrollEventListener()
557 void AddScrollEventListener(IScrollEventListenerF& listener);
560 * Removes an IScrollEventListener instance that listens to the state changes of a scroll event. @n
561 * The removed listener cannot listen to events when they are fired.
565 * @param[in] listener The event listener to remove
566 * @see IScrollEventListener::OnScrollEndReached()
567 * @see AddScrollEventListener()
569 void RemoveScrollEventListener(IScrollEventListener& listener);
572 * Removes an IScrollEventListener instance that listens to the state changes of a scroll event. @n
573 * The removed listener cannot listen to events when they are fired.
577 * @param[in] listener The event listener to remove
578 * @see IScrollEventListener::OnScrollEndReached()
579 * @see AddScrollEventListener()
581 void RemoveScrollEventListener(IScrollEventListenerF& listener);
584 * Adds a link event listener.
588 * @param[in] listener The event listener to add
589 * @remarks The added listener is notified when a link is selected by the user.
591 * @see RemoveUiLinkEventListener()
593 void AddUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
596 * Removes the specified link event listener.
597 * The removed listener cannot listen to events when they are fired.
601 * @param[in] listener The event listener to remove
602 * @see AddUiLinkEventListener()
604 void RemoveUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
607 * Enables or disables the sweep event.
611 * @return An error code
612 * @param[in] enable Set to @c true to enable the item sweep, @n
614 * @exception E_SUCCESS The method is successful.
615 * @exception E_SYSTEM A system error has occurred.
617 result SetSweepEnabled(bool enable);
620 * Sets the index list of the fast scroll.
624 * @return An error code
625 * @param[in] text The text of the index
626 * @param[in] useSearchIcon Set to @c true to display the magnifying icon, @n
628 * @exception E_SUCCESS The method is successful.
629 * @exception E_INVALID_ARG A specified input parameter is invalid.
630 * @exception E_INVALID_STATE This instance is in an invalid state.
631 * @exception E_SYSTEM A system error has occurred.
633 result SetFastScrollIndex(const Tizen::Base::String& text, bool useSearchIcon);
636 * Gets the group and item indexes of the top item.
640 * @return An error code
641 * @param[out] groupIndex The group index
642 * @param[out] itemIndex The item index
643 * @exception E_SUCCESS The method is successful.
644 * @exception E_SYSTEM A system error has occurred.
646 result GetTopDrawnItemIndex(int& groupIndex, int& itemIndex) const;
649 * Gets the group and item indexes of the bottom item.
653 * @return An error code
654 * @param[out] groupIndex The group index
655 * @param[out] itemIndex The item index
656 * @exception E_SUCCESS The method is successful.
657 * @exception E_SYSTEM A system error has occurred.
659 result GetBottomDrawnItemIndex(int& groupIndex, int& itemIndex) const;
663 * Scrolls to the item at the specified index. @n
664 * The specified item is drawn at the top of the %GroupedListView control.
668 * @return An error code
669 * @param[in] groupIndex The group index
670 * @param[in] itemIndex The item index
671 * @exception E_SUCCESS The method is successful.
672 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
673 * @exception E_SYSTEM A system error has occurred.
674 * @remarks This method should be called only after list items are created. @n
675 * If this method needs to be called early in the lifecycle of the ListView,
676 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
678 result ScrollToItem(int groupIndex, int itemIndex);
681 * Scrolls to the item at the specified index. @n
682 * The specified item is drawn at the position specified by the item alignment.
686 * @return An error code
687 * @param[in] groupIndex The group index
688 * @param[in] itemIndex The item index
689 * @param[in] itemAlignment The item alignment
690 * @exception E_SUCCESS The method is successful.
691 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
692 * @exception E_SYSTEM A system error has occurred.
693 * @remarks This method should be called only after list items are created. @n
694 * If this method needs to be called early in the lifecycle of the ListView,
695 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
697 result ScrollToItem(int groupIndex, int itemIndex, ListScrollItemAlignment itemAlignment);
700 * Checks or unchecks the item at the specified index.
704 * @return An error code
705 * @param[in] groupIndex The group index of the item to check
706 * @param[in] itemIndex The index of the item to check
707 * @param[in] check Set to @c true to select the item, @n
709 * @exception E_SUCCESS The method is successful.
710 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
711 * @exception E_INVALID_OPERATION The item is disabled.
712 * @exception E_SYSTEM A system error has occurred.
714 * - This method works only when the annex style of the item allows selection.
715 * - This method should be called only after list items are created. @n
716 * If this method needs to be called early in the lifecycle of the ListView,
717 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
719 result SetItemChecked(int groupIndex, int itemIndex, bool check);
722 * Checks whether the item at the specified index is selected.
726 * @return @c true if the item is selected, @n
728 * @param[in] groupIndex The group index
729 * @param[in] itemIndex The item index
731 * - This method returns @c false, if the annex style of the item does not allow selection.
732 * - This method should be called only after list items are created. @n
733 * If this method needs to be called early in the lifecycle of the ListView,
734 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
736 bool IsItemChecked(int groupIndex, int itemIndex) const;
739 * Enables or disables the item at the specified index.
743 * @return An error code
744 * @param[in] groupIndex The group index
745 * @param[in] itemIndex The item index
746 * @param[in] enable Set to @c true to enable the specified item, @n
748 * @exception E_SUCCESS The method is successful.
749 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
750 * @exception E_SYSTEM A system error has occurred.
752 * - This method can only be used when the annex style of the list allows selection.
753 * - This method should be called only after list items are created. @n
754 * If this method needs to be called early in the lifecycle of the ListView,
755 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
757 result SetItemEnabled(int groupIndex, int itemIndex, bool enable);
760 * Checks whether the item at the specified index is enabled or disabled.
764 * @return @c true if the item is enabled, @n
766 * @param[in] groupIndex The group index
767 * @param[in] itemIndex The item index
768 * @remarks This method should be called only after list items are created. @n
769 * If this method needs to be called early in the lifecycle of the ListView,
770 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
772 bool IsItemEnabled(int groupIndex, int itemIndex) const;
775 * Counts the total number of groups.
779 * @return The total number of groups
781 int GetGroupCount(void) const;
784 * Counts all the items of the specified group.
788 * @return The total number of items in the specified group
789 * @param[in] groupIndex The group index
790 * @remarks This method should be called only after list items are created. @n
791 * If this method needs to be called early in the lifecycle of the ListView,
792 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
794 int GetItemCountAt(int groupIndex) const;
797 * Shows the description text of the specified item.
801 * @return An error code
802 * @param[in] groupIndex The group index of the item
803 * @param[in] itemIndex The index of the item
804 * @exception E_SUCCESS The method is successful.
805 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
806 * @exception E_SYSTEM A system error has occurred.
808 * - If no description text is set for the item at the specified index, it is not displayed.
809 * - This method should be called only after list items are created. @n
810 * If this method needs to be called early in the lifecycle of the ListView,
811 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
814 result ShowItemDescriptionText(int groupIndex, int itemIndex);
817 * Hides the description text of the specified item.
821 * @return An error code
822 * @param[in] groupIndex The group index of the item
823 * @param[in] itemIndex The index of the item
824 * @exception E_SUCCESS The method is successful.
825 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
826 * @exception E_SYSTEM A system error has occurred.
827 * @remarks This method should be called only after list items are created. @n
828 * If this method needs to be called early in the lifecycle of the ListView,
829 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
831 result HideItemDescriptionText(int groupIndex, int itemIndex);
834 * Updates the specified item. @n
835 * For instance, @c LIST_REFRESH_TYPE_ITEM_ADD is used when a new item needs to be added and @c LIST_REFRESH_TYPE_ITEM_REMOVE
836 * is used when an item is deleted from the list. Moreover, @c LIST_REFRESH_TYPE_ITEM_MODIFY is used when the content of an existing item
837 * has changed and it needs to be updated. @n Note that calling this method with @c LIST_REFRESH_TYPE_ITEM_MODIFY invokes item provider's
838 * DeleteItem() and CreateItem() for the given index in sequence.
842 * @return An error code
843 * @param[in] groupIndex The group index
844 * @param[in] itemIndex The item index
845 * @param[in] type The item to add, remove, or modify
846 * @exception E_SUCCESS The method is successful.
847 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
848 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
849 * @exception E_SYSTEM A system error has occurred.
851 * - If the specified itemIndex is @c -1, then the method is applied to the group item with the given index.
852 * - Note that if @c LIST_REFRESH_TYPE_ITEM_REMOVE option is used to a group item, all the items in the group
853 * (including the group item itself) are removed from the list.
854 * - This method internally calls Invalidate(), so you do not need to call them to update the screen.
856 result RefreshList(int groupIndex, int itemIndex, ListRefreshType type);
859 * Refreshes the specified item's element.
863 * @return An error code
864 * @param[in] groupIndex The group index
865 * @param[in] itemIndex The item index
866 * @param[in] elementId The item element ID
867 * @exception E_SUCCESS The method is successful.
868 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
869 * @exception E_SYSTEM A system error has occurred.
870 * @remarks This method internally calls Invalidate(), so you do not need to call them to update the screen.
872 result RefreshList(int groupIndex, int itemIndex, int elementId);
875 * Updates all the items of a list.
879 * @return An error code
880 * @exception E_SUCCESS The method is successful.
881 * @exception E_SYSTEM A system error has occurred.
882 * @remarks This method clears all the items in the list and invokes the methods of the item provider again to update the list.
884 result UpdateList(void);
887 * Gets the index of the item at the specified position.
891 * @return An error code
892 * @param[in] x The X position of the item
893 * @param[in] y The Y position of the item
894 * @param[out] groupIndex The index of the group that the item belongs to
895 * @param[out] itemIndex The index of the item
896 * @exception E_SUCCESS The method is successful.
897 * @exception E_SYSTEM A system error has occurred, or @n
898 * there is no item at the specified position.
899 * @remarks This method should be called only after list items are created. @n
900 * If this method needs to be called early in the lifecycle of the ListView,
901 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
903 result GetItemIndexFromPosition(int x, int y, int& groupIndex, int& itemIndex) const;
906 * Gets the index of the item at the specified position.
910 * @return An error code
911 * @param[in] x The X position of the item
912 * @param[in] y The Y position of the item
913 * @param[out] groupIndex The index of the group that the item belongs to
914 * @param[out] itemIndex The index of the item
915 * @exception E_SUCCESS The method is successful.
916 * @exception E_SYSTEM A system error has occurred, or @n
917 * there is no item at the specified position.
918 * @remarks This method should be called only after list items are created. @n
919 * If this method needs to be called early in the lifecycle of the ListView,
920 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
922 result GetItemIndexFromPosition(float x, float y, int& groupIndex, int& itemIndex) const;
925 * Gets the index of the item at the specified position.
929 * @return An error code
930 * @param[in] position The position of the item
931 * @param[out] groupIndex The index of the group that the item belongs to
932 * @param[out] itemIndex The index of the item
933 * @exception E_SUCCESS The method is successful.
934 * @exception E_SYSTEM A system error has occurred, or @n
935 * there is no item at the specified position.
936 * @remarks This method should be called only after list items are created. @n
937 * If this method needs to be called early in the lifecycle of the ListView,
938 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
940 result GetItemIndexFromPosition(const Tizen::Graphics::Point& position, int& groupIndex, int& itemIndex) const;
943 * Gets the index of the item at the specified position.
947 * @return An error code
948 * @param[in] position The position of the item
949 * @param[out] groupIndex The index of the group that the item belongs to
950 * @param[out] itemIndex The index of the item
951 * @exception E_SUCCESS The method is successful.
952 * @exception E_SYSTEM A system error has occurred, or @n
953 * there is no item at the specified position.
954 * @remarks This method should be called only after list items are created. @n
955 * If this method needs to be called early in the lifecycle of the ListView,
956 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
958 result GetItemIndexFromPosition(const Tizen::Graphics::FloatPoint& position, int& groupIndex, int& itemIndex) const;
961 * Gets the index of the item and ID of the element at the specified position.
965 * @return An error code
966 * @param[in] x The X position of the item
967 * @param[in] y The Y position of the item
968 * @param[out] groupIndex The index of the group that the item belongs to
969 * @param[out] itemIndex The index of the item
970 * @param[out] elementId The ID of the element
971 * @exception E_SUCCESS The method is successful.
972 * @exception E_SYSTEM A system error has occurred, or
973 * there is no item at the specified position.
975 * - @c groupIndex and @c itemIndex are @c -1 when there is no list item at the specified position.
976 * - @c elementId is @c -1 when there is no element at the specified position
977 * - This method should be called only after list items are created. @n
978 * If this method needs to be called early in the lifecycle of the ListView,
979 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
982 result GetItemIndexFromPosition(int x, int y, int& groupIndex, int& itemIndex, int& elementId) const;
985 * Gets the index of the item and ID of the element at the specified position.
989 * @return An error code
990 * @param[in] x The X position of the item
991 * @param[in] y The Y position of the item
992 * @param[out] groupIndex The index of the group that the item belongs to
993 * @param[out] itemIndex The index of the item
994 * @param[out] elementId The ID of the element
995 * @exception E_SUCCESS The method is successful.
996 * @exception E_SYSTEM A system error has occurred, or
997 * there is no item at the specified position.
999 * - @c groupIndex and @c itemIndex are @c -1 when there is no list item at the specified position.
1000 * - @c elementId is @c -1 when there is no element at the specified position
1001 * - This method should be called only after list items are created. @n
1002 * If this method needs to be called early in the lifecycle of the ListView,
1003 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
1005 result GetItemIndexFromPosition(float x, float y, int& groupIndex, int& itemIndex, int& elementId) const;
1008 * Gets the index of the item and ID of the element at the specified position.
1012 * @return An error code
1013 * @param[in] position The position of the point
1014 * @param[out] groupIndex The index of the group that the item belongs to
1015 * @param[out] itemIndex The index of the item
1016 * @param[out] elementId The ID of the element
1017 * @exception E_SUCCESS The method is successful.
1018 * @exception E_SYSTEM A system error has occurred, or
1019 * there is no item at the specified position.
1021 * - @c groupIndex and @c itemIndex are @c -1 when there is no list item at the specified position.
1022 * - @c elementId is @c -1 when there is no element at the specified position
1023 * - This method should be called only after list items are created. @n
1024 * If this method needs to be called early in the lifecycle of the ListView,
1025 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
1027 result GetItemIndexFromPosition(const Tizen::Graphics::Point& position, int& groupIndex, int& itemIndex, int& elementId) const;
1030 * Gets the index of the item and ID of the element at the specified position.
1034 * @return An error code
1035 * @param[in] position The position of the point
1036 * @param[out] groupIndex The index of the group that the item belongs to
1037 * @param[out] itemIndex The index of the item
1038 * @param[out] elementId The ID of the element
1039 * @exception E_SUCCESS The method is successful.
1040 * @exception E_SYSTEM A system error has occurred, or
1041 * there is no item at the specified position.
1043 * - @c groupIndex and @c itemIndex are @c -1 when there is no list item at the specified position.
1044 * - @c elementId is @c -1 when there is no element at the specified position
1045 * - This method should be called only after list items are created. @n
1046 * If this method needs to be called early in the lifecycle of the ListView,
1047 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
1049 result GetItemIndexFromPosition(const Tizen::Graphics::FloatPoint& position, int& groupIndex, int& itemIndex, int& elementId) const;
1052 * Sets the color of a section.
1056 * @return An error code
1057 * @param[in] color The section color
1058 * @exception E_SUCCESS The method is successful.
1059 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation
1060 * (this control cannot be displayed).
1061 * @exception E_SYSTEM A system error has occurred.
1063 * - This method works only when the style of the %GroupedListView control is ::GROUPED_LIST_VIEW_STYLE_SECTION.
1064 * - If the device does not support the 32-bit color space, the method sets the alpha value of the specified color to @c 255.
1066 result SetSectionColor(const Tizen::Graphics::Color& color);
1069 * Gets the color of a section.
1073 * @return The section color, @n
1074 * else RGBA(0, 0, 0, 0) if the instance is invalid
1076 Tizen::Graphics::Color GetSectionColor(void) const;
1079 * Sets the color of a division line between items.
1083 * @return An error code
1084 * @param[in] color The division line color
1085 * @exception E_SUCCESS The method is successful.
1086 * @exception E_SYSTEM A system error has occurred.
1088 result SetItemDividerColor(const Tizen::Graphics::Color& color);
1091 * Gets the color of a division line between items.
1095 * @return The color of a division line, @n
1096 * else RGBA(0, 0, 0, 0) if the instance is invalid
1098 Tizen::Graphics::Color GetItemDividerColor(void) const;
1101 * Sets the background color of this control.
1105 * @return An error code
1106 * @param[in] color The background color
1107 * @exception E_SUCCESS The method is successful.
1109 * - If the device does not support the 32-bit color space, the method sets the alpha value of the specified color to @c 255.
1110 * - The background bitmap has priority over the background color. When both the background bitmap and the background color
1111 * are specified, only the bitmap image is displayed.
1113 result SetBackgroundColor(const Tizen::Graphics::Color& color);
1116 * Gets the background color of this control.
1120 * @return The background color, @n
1121 * else RGBA(0, 0, 0, 0) if the instance is invalid
1123 Tizen::Graphics::Color GetBackgroundColor(void) const;
1126 * Sets the bitmap of this control.
1130 * @return An error code
1131 * @param[in] pBitmap The bitmap for the list
1132 * @exception E_SUCCESS The method is successful.
1133 * @exception E_SYSTEM A system error has occurred.
1135 result SetBackgroundBitmap(const Tizen::Graphics::Bitmap* pBitmap);
1138 * Sets the bitmap of the empty list.
1142 * @return An error code
1143 * @param[in] pBitmap The bitmap for the empty list
1144 * @exception E_SUCCESS The method is successful.
1145 * @exception E_SYSTEM A system error has occurred.
1147 result SetBitmapOfEmptyList(const Tizen::Graphics::Bitmap* pBitmap);
1150 * Sets the text of the empty list.
1154 * @return An error code
1155 * @param[in] text The text for the empty list
1156 * @exception E_SUCCESS The method is successful.
1157 * @exception E_SYSTEM A system error has occurred.
1159 result SetTextOfEmptyList(const Tizen::Base::String& text);
1162 * Gets the text to display when there is no item in a list.
1166 * @return The text to be displayed, @n
1167 * else an empty string when the instance is invalid
1169 Tizen::Base::String GetTextOfEmptyList(void) const;
1172 * Sets the color of the text to be displayed when there is no item in a list.
1176 * @return An error code
1177 * @param[in] color The color of the text to display
1178 * @exception E_SUCCESS The method is successful.
1179 * @exception E_SYSTEM A system error has occurred.
1181 result SetTextColorOfEmptyList(const Tizen::Graphics::Color& color);
1184 * Gets the color of the text to be displayed when there is no item in a list.
1188 * @return The color of the text to be displayed, @n
1189 * else RGBA(0, 0, 0, 0) if the instance is invalid
1191 Tizen::Graphics::Color GetTextColorOfEmptyList(void) const;
1194 * Expands the group's items.
1198 * @return An error code
1199 * @param[in] groupIndex The index of the group
1200 * @exception E_SUCCESS The method is successful.
1201 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
1202 * @exception E_SYSTEM A system error has occurred.
1203 * @remarks This method should be called only after list items are created. @n
1204 * If this method needs to be called early in the lifecycle of the ListView,
1205 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
1207 result ExpandGroup(int groupIndex);
1210 * Collapses the group's items.
1214 * @return An error code
1215 * @param[in] groupIndex The index of the group
1216 * @exception E_SUCCESS The method is successful.
1217 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
1218 * @exception E_SYSTEM A system error has occurred.
1219 * @remarks This method should be called only after list items are created. @n
1220 * If this method needs to be called early in the lifecycle of the ListView,
1221 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
1223 result CollapseGroup(int groupIndex);
1226 * Checks whether the group is expanded.
1230 * @return @c true if the group is expanded, @n
1233 * @param[in] groupIndex The index of the group
1234 * @remarks This method should be called only after list items are created. @n
1235 * If this method needs to be called early in the lifecycle of the ListView,
1236 * then UpdateList() method should be called explicitly (for example, during Tizen::Ui::Control::OnInitializing()).
1238 bool IsGroupExpanded(int groupIndex) const;
1241 * Expands all groups of list.
1245 * @exception E_SUCCESS The method is successful.
1246 * @exception E_INVALID_OPERATION The feature of expanding all groups is only supported when %GroupedListView% is constructed with
1247 * ::GROUPED_LIST_VIEW_STYLE_INDEXED style.
1248 * @see GroupedListView::Construct()
1250 result ExpandAllGroups(void);
1253 * Collapses all groups of list.
1257 * @exception E_SUCCESS The method is successful.
1258 * @exception E_INVALID_OPERATION The feature of collapsing all groups is only supported when %GroupedListView% is constructed with
1259 * ::GROUPED_LIST_VIEW_STYLE_INDEXED style.
1260 * @see GroupedListView::Construct()
1262 result CollapseAllGroups(void);
1265 * Begins the reordering mode.
1269 * @return An error code
1270 * @exception E_SUCCESS The method is successful.
1271 * @exception E_INVALID_OPERATION The reordering mode is only supported when %GroupedListView% is constructed with
1272 * ::GROUPED_LIST_VIEW_STYLE_INDEXED style.
1273 * @see GroupedListView::Construct()
1274 * @see IGroupedListViewItemEventListener::OnGroupedListViewItemReordered()
1276 result BeginReorderingMode(void);
1279 * Ends the reordering mode.
1283 * @return An error code
1284 * @exception E_SUCCESS The method is successful.
1285 * @exception E_INVALID_OPERATION The reordering mode is only supported when %GroupedListView% is constructed with
1286 * ::GROUPED_LIST_VIEW_STYLE_INDEXED style.
1287 * @see GroupedListView::Construct()
1288 * @see IGroupedListViewItemEventListener::OnGroupedListViewItemReordered()
1290 result EndReorderingMode(void);
1293 * Checks whether the %GroupedListView control is in reordering mode.
1297 * @return @c true if the %GroupedListView is in reordering mode,
1300 bool IsInReorderingMode(void) const;
1303 * Sets the scroll input handling mode.
1307 * @param[in] mode The scroll input handling mode
1308 * @see GetScrollInputMode()
1310 void SetScrollInputMode(ScrollInputMode mode);
1313 * Gets the scroll input handling mode.
1317 * @return The scroll input handling mode
1318 * @see SetScrollInputMode()
1320 ScrollInputMode GetScrollInputMode(void) const;
1323 * Opens the context item at a specified index.
1327 * @return An error code
1328 * @param[in] groupIndex The group index
1329 * @param[in] itemIndex The item index
1330 * @exception E_SUCCESS The method is successful.
1331 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
1332 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
1334 result OpenContextItem(int groupIndex, int itemIndex);
1337 * Closes the context item at a specified index.
1341 * @return An error code
1342 * @param[in] groupIndex The group index
1343 * @param[in] itemIndex The item index
1344 * @exception E_SUCCESS The method is successful.
1345 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
1346 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
1348 result CloseContextItem(int groupIndex, int itemIndex);
1351 * Returns whether the context item at a specified index has been opened or not.
1355 * @return @c true if the context item has been opened, @n
1357 * @param[in] groupIndex The group index
1358 * @param[in] itemIndex The item index
1359 * @exception E_SUCCESS The method is successful.
1360 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
1362 bool IsContextItemOpened(int groupIndex, int itemIndex) const;
1365 friend class _GroupedListViewImpl;
1369 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1371 GroupedListView(const GroupedListView& rhs);
1374 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1376 GroupedListView& operator =(const GroupedListView& rhs);
1378 }; // GroupedListView
1380 }}} // Tizen::Ui::Controls
1382 #endif // _FUI_CTRL_GROUPED_LIST_VIEW_H_