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 FUiCtrlListView.h
20 * @brief This is the header file for the %ListView class.
22 * This header file contains the declarations of the %ListView class and its helper classes.
25 #ifndef _FUI_CTRL_LIST_VIEW_H_
26 #define _FUI_CTRL_LIST_VIEW_H_
28 #include <FBaseObject.h>
29 #include <FBaseTypes.h>
30 #include <FGrpRectangle.h>
31 #include <FUiContainer.h>
32 #include <FUiControl.h>
33 #include <FUiCtrlIFastScrollListener.h>
34 #include <FUiCtrlIListViewItemEventListener.h>
35 #include <FUiCtrlIListViewItemProvider.h>
36 #include <FUiCtrlIScrollEventListener.h>
37 #include <FUiCtrlListViewTypes.h>
38 #include <FUiIUiLinkEventListener.h>
40 namespace Tizen { namespace Ui { namespace Controls
47 * @brief This class defines common behavior for a %ListView control.
51 * The %ListView class displays a list of simple and user-configured items. A simple item has a fixed layout consisting of a bitmap
52 * and a text string. A user-configured item in a %ListView instance can have a different layout and height than the other items.
53 * Each user-configured item is composed of elements that can be texts and bitmaps, and is configured using the CustomItem class.
55 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_listviews.htm">ListViews</a>.
57 * The following example demonstrates how to use the %ListView class.
61 //Sample code for ListViewSample.h
65 : public Tizen::Ui::Controls::Form
66 , public Tizen::Ui::Controls::IListViewItemEventListener
67 , public Tizen::Ui::Controls::IListViewItemProvider
72 , __pItemContext(null){}
74 bool Initialize(void);
75 virtual result OnInitializing(void);
76 virtual result OnTerminating(void);
78 // IListViewItemEventListener
79 virtual void OnListViewContextItemStateChanged(Tizen::Ui::Controls::ListView &listView, int index, int elementId, Tizen::Ui::Controls::ListContextItemStatus state);
80 virtual void OnListViewItemStateChanged(Tizen::Ui::Controls::ListView &listView, int index, int elementId, Tizen::Ui::Controls::ListItemStatus status);
81 virtual void OnListViewItemSwept(Tizen::Ui::Controls::ListView &listView, int index, Tizen::Ui::Controls::SweepDirection direction);
83 // IListViewItemProvider
84 virtual Tizen::Ui::Controls::ListItemBase* CreateItem(int index, int itemWidth);
85 virtual bool DeleteItem(int index, Tizen::Ui::Controls::ListItemBase* pItem, int itemWidth);
86 virtual int GetItemCount(void);
89 static const int ID_FORMAT_STRING = 100;
90 static const int ID_FORMAT_BITMAP = 101;
91 static const int ID_CONTEXT_ITEM_1 = 103;
92 static const int ID_CONTEXT_ITEM_2 = 104;
94 Tizen::Graphics::Bitmap* __pHome;
95 Tizen::Graphics::Bitmap* __pMsg;
96 Tizen::Graphics::Bitmap* __pAlarm;
97 Tizen::Graphics::Bitmap* __pCall;
99 Tizen::Ui::Controls::ListView* __pListView;
100 Tizen::Ui::Controls::ListContextItem* __pItemContext;
105 //Sample code for ListViewSample.cpp
107 #include <FGraphics.h>
109 #include "ListViewSample.h"
111 using namespace Tizen::App;
112 using namespace Tizen::Base;
113 using namespace Tizen::Graphics;
114 using namespace Tizen::Media;
115 using namespace Tizen::Ui::Controls;
118 ListViewSample::Initialize(void)
120 Construct(FORM_STYLE_NORMAL);
125 ListViewSample::OnInitializing(void)
127 result r = E_SUCCESS;
129 // Creates an instance of ListView
130 __pListView = new ListView();
131 __pListView->Construct(Rectangle(0, 0, GetClientAreaBounds().width, GetClientAreaBounds().height), true, false);
132 __pListView->SetItemProvider(*this);
133 __pListView->AddListViewItemEventListener(*this);
135 // Adds the list view to the form
136 AddControl(*__pListView);
138 // Creates an instance of ListContextItem
139 __pItemContext = new ListContextItem();
140 __pItemContext->Construct();
141 __pItemContext->AddElement(ID_CONTEXT_ITEM_1, L"Test1");
142 __pItemContext->AddElement(ID_CONTEXT_ITEM_2, L"Test2");
144 // Gets instances of Bitmap
145 AppResource* pAppResource = Application::GetInstance()->GetAppResource();
146 __pHome = pAppResource->GetBitmapN(L"tizen.png");
147 __pMsg = pAppResource->GetBitmapN(L"tizen.png");
148 __pAlarm = pAppResource->GetBitmapN(L"tizen.png");
149 __pCall = pAppResource->GetBitmapN(L"tizen.png");
155 ListViewSample::OnTerminating(void)
157 result r = E_SUCCESS;
159 // Deallocates bitmaps
165 // Deallocates the item context
166 delete __pItemContext;
171 // IListViewItemEventListener implementation
173 ListViewSample::OnListViewItemStateChanged(ListView &listView, int index, int elementId, ListItemStatus status)
177 case ID_FORMAT_BITMAP:
182 case ID_FORMAT_STRING:
193 ListViewSample::OnListViewContextItemStateChanged(ListView &listView, int index, int elementId, ListContextItemStatus state)
197 case ID_CONTEXT_ITEM_1:
202 case ID_CONTEXT_ITEM_2:
213 ListViewSample::OnListViewItemSwept(ListView &listView, int index, SweepDirection direction)
218 // IListViewItemProvider implementation
220 ListViewSample::CreateItem(int index, int itemWidth)
222 // Creates an instance of CustomItem
223 CustomItem* pItem = new CustomItem();
224 ListAnnexStyle style = LIST_ANNEX_STYLE_NORMAL;
230 style = LIST_ANNEX_STYLE_NORMAL;
231 pItem->Construct(Dimension(itemWidth,112), style);
232 pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pHome, null, null);
233 pItem->AddElement(Rectangle(80, 25, 150, 50), ID_FORMAT_STRING, L"Home", true);
238 style = LIST_ANNEX_STYLE_DETAILED;
239 pItem->Construct(Dimension(itemWidth,112), style);
240 pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pMsg, null, null);
241 pItem->AddElement(Rectangle(80, 25, 150, 50), ID_FORMAT_STRING, L"Msg", true);
246 style = LIST_ANNEX_STYLE_ONOFF_SLIDING;
247 pItem->Construct(Dimension(itemWidth,112), style);
248 pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pAlarm, null, null);
249 pItem->AddElement(Rectangle(80, 25, 150, 50), ID_FORMAT_STRING, L"Alarm", true);
254 style = LIST_ANNEX_STYLE_MARK;
255 pItem->Construct(Dimension(itemWidth,112), style);
256 pItem->AddElement(Rectangle(10, 20, 60, 60), ID_FORMAT_BITMAP, *__pCall, null, null);
257 pItem->AddElement(Rectangle(80, 25, 150, 50), ID_FORMAT_STRING, L"Call", true);
264 pItem->SetContextItem(__pItemContext);
270 ListViewSample::DeleteItem(int index, ListItemBase* pItem, int itemWidth)
278 ListViewSample::GetItemCount(void)
285 class _OSP_EXPORT_ ListView
286 : public Tizen::Ui::Control
290 * The object is not fully constructed after this constructor is
291 * called. For full construction, the Construct() method must be
292 * called right after calling this constructor.
299 * This destructor overrides Tizen::Base::Object::~Object().
303 virtual ~ListView(void);
307 * Initializes this instance of %ListView with the specified parameters.
309 * @brief <i> [Deprecated] </i>
310 * @deprecated This method is deprecated.
313 * @return An error code
314 * @param[in] rect An instance of the Graphics::Rectangle class @n
315 * This instance represents the x and y coordinates of the left top corner of the created %ListView along with the width
317 * @param[in] itemDivider Set to @c true to display an item divider, @n
319 * @param[in] fastScroll Set to @c true to use fast scroll, @n
321 * @exception E_SUCCESS The method is successful.
322 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
323 * Either the @c rect.width or @c rect.height parameter has a negative value.
324 * @exception E_SYSTEM A system error has occurred.
327 result Construct(const Tizen::Graphics::Rectangle& rect, bool itemDivider = true, bool fastScroll = false);
330 * Initializes this instance of %ListView with the specified parameters.
334 * @return An error code
335 * @param[in] rect An instance of the Graphics::Rectangle class @n
336 * This instance represents the x and y coordinates of the left top corner of the created %ListView along with the width
338 * @param[in] itemDivider Set to @c true to display an item divider, @n
340 * @param[in] scrollStyle Set to scroll style
341 * @exception E_SUCCESS The method is successful.
342 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
343 * Either the @c rect.width or @c rect.height parameter has a negative value.
344 * @exception E_SYSTEM A system error has occurred.
346 result Construct(const Tizen::Graphics::Rectangle& rect, bool itemDivider, ListScrollStyle scrollStyle);
349 * Sets the item provider that creates and deletes items for the list.
353 * @return An error code
354 * @param[in] provider The item provider to create and delete items
355 * @exception E_SUCCESS The method is successful.
356 * @exception E_SYSTEM A system error has occurred.
357 * @remarks If an item provider is not set for the list, the list does not work. @n
358 * The specified @c provider should be allocated in heap memory.
360 result SetItemProvider(IListViewItemProvider& provider);
364 * Adds a listener instance that listens to state changes of list view items. @n
365 * The added listener can listen to events on the specified event dispatcher's context when they are fired.
369 * @param[in] listener The event listener to add
371 void AddListViewItemEventListener(IListViewItemEventListener& listener);
374 * Removes a listener instance that listens to state changes of list view items. @n
375 * The removed listener cannot listen to events when they are fired.
379 * @param[in] listener The event listener to remove
381 void RemoveListViewItemEventListener(IListViewItemEventListener& listener);
384 * Adds a listener instance that listens to state changes of a fast scroll. @n
385 * The added listener can listen to events on the specified event dispatcher's context when they are fired.
389 * @param[in] listener The event listener to add
391 void AddFastScrollListener(IFastScrollListener& listener);
394 * Removes a listener instance that listens to state changes of a fast scroll. @n
395 * The removed listener cannot listen to events when they are fired.
399 * @param[in] listener The event listener to remove
401 void RemoveFastScrollListener(IFastScrollListener& listener);
404 * Adds a listener instance that listens to state changes of a scroll event. @n
405 * The added listener can listen to events on the specified event dispatcher's context when they are fired.
409 * @param[in] listener The event listener to add
410 * @see IScrollEventListener::OnScrollEndReached()
411 * @see RemoveScrollEventListener()
413 void AddScrollEventListener(IScrollEventListener& listener);
416 * Removes a listener instance that listens to state changes of a scroll event. @n
417 * The removed listener cannot listen to events when they are fired.
421 * @param[in] listener The event listener to remove
422 * @see IScrollEventListener::OnScrollEndReached()
423 * @see AddScrollEventListener()
425 void RemoveScrollEventListener(IScrollEventListener& listener);
428 * Adds a link event listener.
432 * @param[in] listener The event listener to add
433 * @remarks The added listener is notified when a link is selected by the user.
434 * @see RemoveUiLinkEventListener()
436 void AddUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
439 * Removes the specified link event listener. @n
440 * The removed listener cannot listen to events when they are fired.
444 * @param[in] listener The event listener to remove
445 * @see AddUiLinkEventListener()
447 void RemoveUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
450 * Sets the sweep event to enable.
454 * @return An error code
455 * @param[in] enable Set to @c true to enable the sweep, @n
457 * @exception E_SUCCESS The method is successful.
458 * @exception E_SYSTEM A system error has occurred.
460 result SetSweepEnabled(bool enable);
463 * Sets the index list of the scroll by texts.
467 * @return An error code
468 * @param[in] text The text of the index
469 * @param[in] useSearchIcon Set to @c true to show the magnifying icon, @n
471 * @exception E_SUCCESS The method is successful.
472 * @exception E_INVALID_ARG A specified input parameter is invalid.
473 * @exception E_INVALID_STATE This instance is in an invalid state.
474 * @exception E_SYSTEM A system error has occurred.
476 result SetFastScrollIndex(const Tizen::Base::String& text, bool useSearchIcon);
479 * Gets the index of the top drawn item of the %ListView control.
483 * @return The index of the top drawn item
485 int GetTopDrawnItemIndex(void) const;
488 * Gets the index of the bottom drawn item of the %ListView control.
492 * @return The index of the bottom drawn item
494 int GetBottomDrawnItemIndex(void) const;
497 * Scrolls to the item at the specified index. @n
498 * The specified item is drawn at the top of the %ListView control.
502 * @return An error code
503 * @param[in] index The item index
504 * @exception E_SUCCESS The method is successful.
505 * @exception E_OUT_OF_RANGE The specified input parameter is invalid.
506 * @exception E_SYSTEM A system error has occurred.
508 result ScrollToItem(int index);
511 * Scrolls to the item at the specified index. @n
512 * The specified item is drawn at the position specified by the item alignment.
516 * @return An error code
517 * @param[in] index The item index
518 * @param[in] itemAlignment The item alignment
519 * @exception E_SUCCESS The method is successful.
520 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
521 * @exception E_SYSTEM A system error has occurred.
523 result ScrollToItem(int index, ListScrollItemAlignment itemAlignment);
526 * Sets the check status of the item at the specified index.
530 * @return An error code
531 * @param[in] index The item index
532 * @param[in] check The check status
533 * @exception E_SUCCESS The method is successful.
534 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
535 * @exception E_INVALID_OPERATION The item is disabled.
536 * @exception E_SYSTEM A system error has occurred.
538 result SetItemChecked(int index, bool check);
541 * Checks whether the item at the specified index is checked.
545 * @return @c true if the item is checked, @n
547 * @param[in] index The item index
549 bool IsItemChecked(int index) const;
552 * Sets the enabled/disabled status of the item at the specified index.
556 * @return An error code
557 * @param[in] index The item index
558 * @param[in] enable The enabled/disabled status
559 * @exception E_SUCCESS The method is successful.
560 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
561 * @exception E_SYSTEM A system error has occurred.
564 result SetItemEnabled(int index, bool enable);
567 * Checks whether the item at the specified index is enabled.
571 * @return @c true if the item is enabled, @n
573 * @param[in] index The item index
575 bool IsItemEnabled(int index) const;
578 * Counts the number of items.
582 * @return The total number of items
584 int GetItemCount(void) const;
587 * Shows the description text of the given item.
591 * @return An error code
592 * @param[in] index The index of the item
593 * @exception E_SUCCESS The method is successful.
594 * @exception E_OUT_OF_RANGE The specified input parameter is invalid.
595 * @exception E_SYSTEM A system error has occurred.
596 * @remarks If no description text is set to the item of the specified index, this method does not show the description text.
599 result ShowItemDescriptionText(int index);
602 * Hides the description text of the given item.
606 * @return An error code
607 * @param[in] index The index of the item
608 * @exception E_SUCCESS The method is successful.
609 * @exception E_OUT_OF_RANGE The specified input parameter is invalid.
610 * @exception E_SYSTEM A system error has occurred.
612 result HideItemDescriptionText(int index);
615 * Refreshes the specified item.
619 * @return An error code
620 * @param[in] index The item index
621 * @param[in] type The item to be added, removed, or modified
622 * @exception E_SUCCESS The method is successful.
623 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
624 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
625 * @exception E_SYSTEM A system error has occurred.
626 * @remarks 3 refresh types are supported: LIST_REFRESH_TYPE_ITEM_ADD, LIST_REFRESH_TYPE_ITEM_REMOVE, and LIST_REFRESH_TYPE_ITEM_MODIFY.
627 * - LIST_REFRESH_TYPE_ITEM_ADD is used when new data is added to the data model. @n
628 * - LIST_REFRESH_TYPE_ITEM_REMOVE is used when a data is deleted from the data model. @n
629 * - LIST_REFRESH_TYPE_ITEM_MODIFY is used when an existing data has changes and needs to be updated. @n
630 * Calling this method with LIST_REFRESH_TYPE_ITEM_MODIFY invokes the item provider to call DeleteItem() and CreateItem() for the given index in
632 * @remarks This method internally calls Invalidate(), so you do not need to call them to update the screen.
634 result RefreshList(int index, ListRefreshType type);
637 * Refreshes the specified item's element.
641 * @return An error code
642 * @param[in] index The item index
643 * @param[in] elementId The item element ID
644 * @exception E_SUCCESS The method is successful.
645 * @exception E_OUT_OF_RANGE A specified input parameter is invalid.
646 * @exception E_SYSTEM A system error has occurred.
647 * @remarks This method internally calls Invalidate(), so you do not need to call them to update the screen.
649 result RefreshList(int index, int elementId);
652 * Updates the whole items of a list.
656 * @return An error code
657 * @exception E_SUCCESS The method is successful.
658 * @exception E_SYSTEM A system error has occurred.
659 * @remarks This method clears the items in the list and re-invokes the methods of the item provider to fill the list.
661 result UpdateList(void);
664 * Gets the index of the item at the specified position.
668 * @return The index of the item, @n
669 * else @c -1 if there is no list item at the specified position
670 * @param[in] x The X position of the point
671 * @param[in] y The Y position of the point
672 * @remarks The method returns -1 when there is no list item at the specified position.
674 int GetItemIndexFromPosition(int x, int y) const;
677 * Gets the index of the item at the specified position.
681 * @return The index of the item
682 * @param[in] position The position of the point, @n
683 * else @c -1 if there is no list item at the specified position
685 int GetItemIndexFromPosition(const Tizen::Graphics::Point& position) const;
688 * Gets the index of the item and ID of the element at the specified position.
692 * @return An error code
693 * @param[in] x The X position of the item
694 * @param[in] y The Y position of the item
695 * @param[out] itemIndex The index of the item
696 * @param[out] elementId The ID of the element
697 * @exception E_SUCCESS The method is successful.
698 * @exception E_SYSTEM A system error has occurred, or @n
699 * there is no item at the specified position.
700 * @remarks The specified @c itemIndex is -1 when there is no list item at the specified position.
701 * @remarks The specified @c elementId is -1 when there is no element at the specified position.
703 result GetItemIndexFromPosition(int x, int y, int& itemIndex, int& elementId) const;
706 * Gets the index of the item and ID of the element at the specified position.
710 * @return An error code
711 * @param[in] position The position of the point
712 * @param[out] itemIndex The index of the item
713 * @param[out] elementId The ID of the element
714 * @exception E_SUCCESS The method is successful.
715 * @exception E_SYSTEM A system error has occurred, or @n
716 * there is no item at the specified position.
717 * @remarks The specified @c itemIndex is -1 when there is no list item at the specified position.
718 * @remarks The specified @c elementId is -1 when there is no element at the specified position.
720 result GetItemIndexFromPosition(const Tizen::Graphics::Point& position, int& itemIndex, int& elementId) const;
723 * Sets the color of a division line between items.
727 * @return An error code
728 * @param[in] color The division line color
729 * @exception E_SUCCESS The method is successful.
731 result SetItemDividerColor(const Tizen::Graphics::Color& color);
734 * Gets the color of a division line between items.
738 * @return The color of a section, @n
739 * else RGBA(0, 0, 0, 0) if the instance is invalid
741 Tizen::Graphics::Color GetItemDividerColor(void) const;
744 * Sets the background color of this control.
748 * @return An error code
749 * @param[in] color The background color
750 * @exception E_SUCCESS The method is successful.
751 * @remarks The method sets the alpha value of the specified @c color to @c 255, when a device does not support 32bit color space. @n
752 * The background bitmap has priority over the background color. When both the background bitmap and the background color are specified, only
753 * the bitmap image is displayed.
755 result SetBackgroundColor(const Tizen::Graphics::Color& color);
758 * Gets the background color of this control.
762 * @return The background color, @n
763 * else RGBA(0, 0, 0, 0) if the instance is invalid
765 Tizen::Graphics::Color GetBackgroundColor(void) const;
768 * Sets the bitmap of this control.
772 * @return An error code
773 * @param[in] pBitmap The bitmap for the list
774 * @exception E_SUCCESS The method is successful.
775 * @exception E_SYSTEM A system error has occurred.
777 result SetBackgroundBitmap(const Tizen::Graphics::Bitmap* pBitmap);
780 * Sets the bitmap of the empty list.
784 * @return An error code
785 * @param[in] pBitmap The bitmap for the empty list
786 * @exception E_SUCCESS The method is successful.
787 * @exception E_SYSTEM A system error has occurred.
789 result SetBitmapOfEmptyList(const Tizen::Graphics::Bitmap* pBitmap);
792 * Sets the text of the empty list.
796 * @return An error code
797 * @param[in] text The text for the empty list
798 * @exception E_SUCCESS The method is successful.
799 * @exception E_SYSTEM A system error has occurred.
801 result SetTextOfEmptyList(const Tizen::Base::String& text);
804 * Gets the text to display when there is no item in a list.
808 * @return The text to display, @n
809 * else an empty string if the instance is invalid
811 Tizen::Base::String GetTextOfEmptyList(void) const;
814 * Sets a color of the text to display when there is no item in a list.
818 * @return An error code
819 * @param[in] color The color of the text to display
820 * @exception E_SUCCESS The method is successful.
821 * @exception E_SYSTEM A system error has occurred.
823 result SetTextColorOfEmptyList(const Tizen::Graphics::Color& color);
826 * Gets a color of the text to display when there is no item in a list.
830 * @return The color of the text to display
832 Tizen::Graphics::Color GetTextColorOfEmptyList(void) const;
835 * Begins the reordering mode.
839 * @return An error code
840 * @exception E_SUCCESS The method is successful.
841 * @exception E_SYSTEM A system error has occurred.
842 * @see IListViewItemEventListener::OnListViewItemReordered()
844 result BeginReorderingMode(void);
847 * Ends the reordering mode.
851 * @return An error code
852 * @exception E_SUCCESS The method is successful.
853 * @exception E_SYSTEM A system error has occurred.
854 * @see IListViewItemEventListener::OnListViewItemReordered()
856 result EndReorderingMode(void);
859 * Checks whether the %ListView control is in reordering mode.
863 * @return @c true if the %ListView is in reordering mode, @n
866 bool IsInReorderingMode(void) const;
869 friend class _ListViewImpl;
873 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
875 ListView(const ListView& rhs);
878 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
880 ListView& operator =(const ListView& rhs);
883 }}} // Tizen::Ui::Controls
885 #endif // _FUI_CTRL_LIST_VIEW_H_