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.
20 * @file FUiCtrlCustomList.h
21 * @brief This is the header file for the %CustomList class.
23 * This header file contains the declarations of the %CustomList class and its helper classes.
27 #ifndef _FUI_CTRL_CUSTOM_LIST_H_
28 #define _FUI_CTRL_CUSTOM_LIST_H_
30 #include <FBaseObject.h>
31 #include <FBaseTypes.h>
32 #include <FGrpRectangle.h>
33 #include <FUiControl.h>
34 #include <FUiContainer.h>
35 #include <FUiCtrlCustomListTypes.h>
36 #include <FUiICustomItemEventListener.h>
37 #include <FUiCtrlCustomListItem.h>
38 #include <FUiCtrlListTypes.h>
40 namespace Tizen { namespace Ui { namespace Controls
46 * @brief <i> [Deprecated] </i> This class defines the common behavior of a %CustomList control.
48 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
51 * The %CustomList class represents a list which has user-configured items. An item in a custom list can have
52 * different layout and height than the other items. Each item is composed of elements, which can be texts and bitmaps
53 * and is configured using CustomListItem and CustomListItemFormat.
55 * When an item in a custom list is selected or deselected, an item event is generated. It is passed on to all item event listeners
56 * that have registered an interest in item events generated by the custom list. If an application wants to perform tasks when a custom
57 * list item is selected and deselected, it must implement ICustomItemEventListener and register the listener to receive events from
58 * the custom list by calling the custom list's AddCustomItemEventListener() method.
60 * Note that CustomListItem and CustomListItemFormat need to be created on a heap. The items of a custom list are deleted automatically
61 * when the %CustomList control is destroyed. If you want to remove certain list items, you must use RemoveItemAt(). CustomListItemFormat
62 * must be deleted by the application.
64 * Refer to CustomListItem and CustomListItemFormat.
68 * @image html ui_controls_customlist.png
71 * This is a simple UI application that uses a %CustomList control.
75 //Sample code for CustomListSample.h
78 // Forward Declaration
79 class CustomListElement;
81 class CustomListSample
82 : public Tizen::Ui::Controls::Form
83 , public Tizen::Ui::ICustomItemEventListener
86 CustomListSample(void)
88 , __pCustomListItemFormat(null)
89 , __pListElement(null){}
91 bool Initialize(void);
92 result AddListItem(Tizen::Ui::Controls::CustomList& customList, Tizen::Base::String itemText,
93 Tizen::Graphics::Bitmap* pBitmapNormal, Tizen::Graphics::Bitmap* pBitmapFocused);
95 virtual result OnInitializing(void);
96 virtual result OnTerminating(void);
98 // ICustomItemEventListener
99 virtual void OnItemStateChanged(const Tizen::Ui::Control& source, int index, int itemId, Tizen::Ui::ItemStatus status);
100 virtual void OnItemStateChanged(const Tizen::Ui::Control& source, int index, int itemId, int elementId, Tizen::Ui::ItemStatus status);
103 static const int ID_LIST_ITEM = 101;
104 static const int ID_LIST_TEXT = 102;
105 static const int ID_LIST_BITMAP = 103;
106 static const int ID_FORMAT_CUSTOM = 104;
108 Tizen::Ui::Controls::CustomList* __pCustomList;
109 Tizen::Ui::Controls::CustomListItemFormat* __pCustomListItemFormat;
110 CustomListElement* __pListElement;
115 // Sample code for CutomListSample.cpp
117 #include <FGraphics.h>
119 #include "CustomListSample.h"
121 using namespace Tizen::App;
122 using namespace Tizen::Base;
123 using namespace Tizen::Graphics;
124 using namespace Tizen::Ui;
125 using namespace Tizen::Ui::Controls;
127 class CustomListElement
128 : public ICustomListElement
132 DrawElement(const Tizen::Graphics::Canvas& canvas, const Tizen::Graphics::Rectangle& rect, CustomListItemStatus itemStatus)
134 result r = E_SUCCESS;
136 Canvas* pCanvas = const_cast<Canvas*>(&canvas);
138 pCanvas->SetLineWidth(5);
139 pCanvas->SetForegroundColor(Color::GetColor(COLOR_ID_GREEN));
140 if (pCanvas->DrawRectangle(rect) != E_SUCCESS)
145 if (pCanvas->DrawText(Point(rect.x+20, rect.y+20), L"Custom") != E_SUCCESS)
155 CustomListSample::Initialize()
157 Construct(FORM_STYLE_NORMAL);
162 CustomListSample::OnInitializing(void)
164 result r = E_SUCCESS;
166 // Creates an instance of CustomListElement
167 __pListElement = new CustomListElement();
169 // Creates an instance of CustomList
170 __pCustomList = new CustomList();
171 __pCustomList->Construct(Rectangle(0, 0, GetClientAreaBounds().width, GetClientAreaBounds().height), CUSTOM_LIST_STYLE_NORMAL);
172 __pCustomList->AddCustomItemEventListener(*this);
174 // Creates an instance of CustomListItemFormat
175 __pCustomListItemFormat = new CustomListItemFormat();
176 __pCustomListItemFormat->Construct();
177 __pCustomListItemFormat->AddElement(ID_LIST_TEXT, Rectangle(10, 25, 150, 80));
178 __pCustomListItemFormat->AddElement(ID_LIST_BITMAP, Rectangle(170, 10, 70, 80));
179 __pCustomListItemFormat->AddElement(ID_FORMAT_CUSTOM, Rectangle(GetClientAreaBounds().width - 120, 20, 100, 60));
180 __pCustomListItemFormat->SetElementEventEnabled(ID_LIST_TEXT, true);
181 __pCustomListItemFormat->SetElementEventEnabled(ID_LIST_BITMAP, true);
182 __pCustomListItemFormat->SetElementEventEnabled(ID_FORMAT_CUSTOM, true);
184 // Gets instances of Bitmap
185 AppResource* pAppResource = Application::GetInstance()->GetAppResource();
186 Bitmap *pBitmapNormal = pAppResource->GetBitmapN(L"tizen.png");
187 Bitmap *pBitmapFocused = pAppResource->GetBitmapN(L"tizen.png");
189 // Adds the item to the custom list
190 for (int i = 0; i < 30; i++)
192 String str = L"Text";
194 AddListItem(*__pCustomList, str, pBitmapNormal, pBitmapFocused);
197 // Adds the custom list to the form
198 AddControl(__pCustomList);
200 // Deallocates bitmaps
201 delete pBitmapNormal;
202 delete pBitmapFocused;
208 CustomListSample::OnTerminating(void)
210 result r = E_SUCCESS;
212 // Deallocates item format and the element
213 delete __pCustomListItemFormat;
214 delete __pListElement;
220 CustomListSample::AddListItem(CustomList& customList, String itemText, Bitmap* pBitmapNormal, Bitmap* pBitmapFocused)
222 // Creates an instance of CustomListItem
223 CustomListItem* pItem = new CustomListItem();
225 pItem->Construct(100);
226 pItem->SetItemFormat(*__pCustomListItemFormat);
227 pItem->SetElement(ID_LIST_TEXT, itemText);
228 pItem->SetElement(ID_LIST_BITMAP, *pBitmapNormal, pBitmapFocused);
229 pItem->SetElement(ID_FORMAT_CUSTOM, *(static_cast<ICustomListElement *>(__pListElement)));
231 customList.AddItem(*pItem, ID_LIST_ITEM);
236 // ICustomItemEventListener implementation
238 CustomListSample::OnItemStateChanged(const Control& source, int index, int itemId, ItemStatus status)
253 CustomListSample::OnItemStateChanged(const Control& source, int index, int itemId, int elementId, Tizen::Ui::ItemStatus status)
284 class _OSP_EXPORT_ CustomList
285 : public Tizen::Ui::Control
290 * The object is not fully constructed after this constructor is called. @n
291 * For full construction, the CustomList::Construct() method must be called right after calling this constructor.
293 * @brief <i> [Deprecated] </i>
294 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
302 * This polymorphic destructor should be overridden if required. @n
303 * This way, the destructors of the derived classes are called when the destructor of this interface is called.
305 * @brief <i> [Deprecated] </i>
306 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
310 virtual ~CustomList(void);
315 * Initializes this instance of %CustomList with the specified parameters.
317 * @brief <i> [Deprecated] </i>
318 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
321 * @return An error code
322 * @param[in] rect The x and y position of the top-left corner of the %CustomList control along with the width and height of the control
323 * @param[in] style The style set of %CustomList
324 * @param[in] itemDivider Set to @c true to display the divider, @n
326 * @exception E_SUCCESS The method is successful.
327 * @exception E_INVALID_ARG A specified input parameter is invalid.
328 * @exception E_SYSTEM A system error has occurred.
330 * - The size of the control must be within the range as defined by the minimum and maximum size.
331 * - The minimum size of this control is 92 x 72 on a WVGA screen, 60 x 48 on a HVGA screen and 46 x 36 on a WQVGA screen.
334 result Construct(const Tizen::Graphics::Rectangle& rect, CustomListStyle style, bool itemDivider = true);
339 * Adds the custom item event listener instance. @n
340 * The added listener gets notified when the state of CustomListItem is changed.
342 * @brief <i> [Deprecated] </i>
343 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
346 * @param[in] listener The event listener to add
349 void AddCustomItemEventListener(Tizen::Ui::ICustomItemEventListener& listener);
353 * Removes the custom item event listener instance. @n
354 * The removed listener is not notified even when custom item events are fired.
356 * @brief <i> [Deprecated] </i>
357 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
360 * @param[in] listener The event listener to remove
363 void RemoveCustomItemEventListener(Tizen::Ui::ICustomItemEventListener& listener);
367 * Adds the specified item to the %CustomList control.
369 * @brief <i> [Deprecated] </i>
370 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
373 * @return An error code
374 * @param[in] item The custom list item to add
375 * @param[in] itemId The item ID for the item
376 * @exception E_SUCCESS The method is successful.
377 * @exception E_SYSTEM A system error has occurred.
379 * - The specified @c itemId can be used to identify a specific CustomListItem or
380 * to associate user-allocated resources.
381 * - Note that the custom list does not throw an exception if the same itemID is assigned to multiple items.
382 * - The added item is deleted automatically when the list is destroyed.
383 * - Do not add, insert, or set an item that already belongs to the %CustomList control.
386 result AddItem(const CustomListItem& item, int itemId = LIST_ITEM_UNSPECIFIED_ID);
390 * Inserts the specified item to %CustomList at the specified index.
392 * @brief <i> [Deprecated] </i>
393 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
396 * @return An error code
397 * @param[in] index The index at which to insert the item
398 * @param[in] item The custom list item to insert
399 * @param[in] itemId The item ID for the item
400 * @exception E_SUCCESS The method is successful.
401 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
402 * The specified @c index is less than @c 0 or greater than or equal to the item count.
403 * @exception E_SYSTEM A system error has occurred.
405 * - The inserted item is deleted automatically when the list is destroyed.
406 * - Do not add, insert, or set an item that already belongs to the %CustomList control.
409 result InsertItemAt(int index, const CustomListItem& item, int itemId = LIST_ITEM_UNSPECIFIED_ID);
413 * Sets the contents of the item at the specified index in the %CustomList control.
415 * @brief <i> [Deprecated] </i>
416 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
419 * @return An error code
420 * @param[in] index The index at which to set the contents of the item
421 * @param[in] item The custom list item to set
422 * @param[in] itemId The item ID for the item
423 * @exception E_SUCCESS The method is successful.
424 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
425 * The specified @c index is less than @c 0 or greater than or equal to the item count.
426 * @exception E_SYSTEM A system error has occurred.
427 * @remarks Do not add, insert, or set an item that already belongs to the %CustomList control.
430 result SetItemAt(int index, const CustomListItem& item, int itemId = LIST_ITEM_UNSPECIFIED_ID);
434 * Removes the item at the specified index in the %CustomList control.
436 * @brief <i> [Deprecated] </i>
437 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
440 * @return An error code
441 * @param[in] index The index of the item to delete
442 * @exception E_SUCCESS The method is successful.
443 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
444 * The specified @c index is less than @c 0 or greater than or equal to the item count.
445 * @exception E_SYSTEM A system error has occurred.
446 * @remarks The removed list item is deleted from the memory.
449 result RemoveItemAt(int index);
453 * Removes all the items from the %CustomList control.
455 * @brief <i> [Deprecated] </i>
456 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
459 * @return An error code
460 * @exception E_SUCCESS The method is successful.
461 * @exception E_SYSTEM A system error has occurred.
462 * @remarks The removed list items are deleted from the memory.
465 result RemoveAllItems(void);
469 * Gets the item at the specified index in the %CustomList control.
471 * @brief <i> [Deprecated] </i>
472 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
475 * @return A custom list item, @n
476 * else @c null if the specified index is out of range
477 * @param[in] index The index of the item to get
480 const CustomListItem* GetItemAt(int index) const;
484 * Gets the number of items in the %CustomList control.
486 * @brief <i> [Deprecated] </i>
487 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
490 * @return The number of items in %CustomList, @n
491 * else @c -1 if an error occurs
494 int GetItemCount(void) const;
498 * Enables or disables the status of the item at the specified @c index in the %CustomList control.
500 * @brief <i> [Deprecated] </i>
501 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
504 * @return An error code
505 * @param[in] index The index of the item whose status is to set
506 * @param[in] enable Set to @c true to enable, @n
508 * @exception E_SUCCESS The method is successful.
509 * @exception E_SYSTEM A system error has occurred.
512 result SetItemEnabled(int index, bool enable);
516 * Checks whether the specified index in the %CustomList control is enabled.
518 * @brief <i> [Deprecated] </i>
519 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
522 * @return @c true if the item is enabled, @n
524 * @param[in] index The index of the item to check
527 bool IsItemEnabled(int index) const;
531 * Sets the check status of the item at the specified index in the %CustomList control.
533 * @brief <i> [Deprecated] </i>
534 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
537 * @return An error code
538 * @param[in] index The index of the item to set
539 * @param[in] check The check status
540 * @exception E_SUCCESS The method is successful.
541 * @exception E_SYSTEM A system error has occurred.
542 * @remarks This method can only be used when the style of the list allows selection.
545 result SetItemChecked(int index, bool check);
549 * Checks whether the item at the specified index is checked in the %CustomList control.
551 * @brief <i> [Deprecated] </i>
552 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
555 * @return @c true if the item is checked, @n
557 * @param[in] index The index of the item to check
558 * @remarks This method can only be used when the style of the list allows selection.
561 bool IsItemChecked(int index) const;
565 * Sets the check status for all items of the %CustomList control.
567 * @brief <i> [Deprecated] </i>
568 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
571 * @return An error code
572 * @param[in] check The check status
573 * @exception E_SUCCESS The method is successful.
574 * @exception E_SYSTEM A system error has occurred.
575 * @remarks This method can only be used when the style of the list allows multiple selections.
578 result SetAllItemsChecked(bool check);
583 * Removes the checked items of the %CustomList control.
585 * @brief <i> [Deprecated] </i>
586 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
589 * @return An error code
590 * @exception E_SUCCESS The method is successful.
591 * @exception E_SYSTEM A system error has occurred.
593 * - This method can only be used when the style of the list allows multiple selections.
594 * - The removed list items are deleted from the memory.
597 result RemoveAllCheckedItems(void);
601 * Gets the first item of all the checked items in the %CustomList control.
603 * @brief <i> [Deprecated] </i>
604 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
607 * @return The index of the first checked item, @n
608 * else @c -1 if no item is checked or an error occurs
611 int GetFirstCheckedItemIndex(void) const;
615 * Gets the last item of all the checked items in the %CustomList control.
617 * @brief <i> [Deprecated] </i>
618 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
621 * @return The index of the last checked item, @n
622 * else @c -1 if no item is checked or an error occurs
625 int GetLastCheckedItemIndex(void) const;
629 * Gets the next checked item from the specified index in the %CustomList control.
631 * @brief <i> [Deprecated] </i>
632 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
635 * @return The index of the next checked item @n
636 * else @c -1 if no more item after the specified index is checked, @n
637 * or the specified @c index is less than @c 0 or greater than the item count.
638 * @param[in] index The index of the %CustomList control item
641 int GetNextCheckedItemIndexAfter(int index) const;
645 * Gets the index of the item at the specified position.
647 * @brief <i> [Deprecated] </i>
648 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
651 * @return The index of the item, @n
652 * else @c -1 if the specified position is not inside any of the items
653 * @param[in] x The x position of the point
654 * @param[in] y The y position of the point
657 int GetItemIndexFromPosition(int x, int y) const;
661 * Gets the index of the item at the specified position.
663 * @brief <i> [Deprecated] </i>
664 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
667 * @return The index of the item, @n
668 * else @c -1 if the specified position is not inside any of the items
669 * @param[in] position The position of the point
672 int GetItemIndexFromPosition(const Tizen::Graphics::Point& position) const;
676 * Gets the index of the first item from the visible items in the %CustomList control.
678 * @brief <i> [Deprecated] </i>
679 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
682 * @return The index of the first item, @n
683 * else @c -1 if no item is visible
686 int GetTopDrawnItemIndex(void) const;
690 * Gets the index of the last item from the visible items in the %CustomList control.
692 * @brief <i> [Deprecated] </i>
693 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
696 * @return The index of the last item, @n
697 * else @c -1 if no item is visible
700 int GetBottomDrawnItemIndex(void) const;
704 * Sets the background color of the %CustomList control.
706 * @brief <i> [Deprecated] </i>
707 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
710 * @param[in] color The background color
713 void SetBackgroundColor(const Tizen::Graphics::Color& color);
717 * Sets the text to be displayed when there is no item in the %CustomList control.
719 * @brief <i> [Deprecated] </i>
720 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
723 * @param[in] text The text message to display
726 void SetTextOfEmptyList(const Tizen::Base::String& text);
730 * Sets the color of the text to be displayed when there is no item in the %CustomList control.
732 * @brief <i> [Deprecated] </i>
733 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
736 * @param[in] color The color of the text to display
739 void SetTextColorOfEmptyList(const Tizen::Graphics::Color& color);
743 * Gets the color of the text to display when there is no item in the CustomList control.
745 * @brief <i> [Deprecated] </i>
746 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
749 * @return The color of the text to be displayed
752 Tizen::Graphics::Color GetTextColorOfEmptyList(void) const;
756 * Gets the index of the item.
758 * @brief <i> [Deprecated] </i>
759 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
762 * @return The index of the item, @n
763 * else @c -1 if no item has the specified item ID
764 * @param[in] itemId The item ID of the %CustomList control item
765 * @remarks One or more indexes can have the same item ID, @n
766 * and this method returns the first item from such items.
769 int GetItemIndexFromItemId(int itemId) const;
773 * Gets the item ID of the item at the specified index.
775 * @brief <i> [Deprecated] </i>
776 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
779 * @return The item ID of the item, @n
780 * else @c -1 if the specified @c index is less than @c 0 or greater than the item count
781 * @param[in] index The index of the %CustomList control item
784 int GetItemIdAt(int index) const;
788 * Scrolls to the bottom of the %CustomList control.
790 * @brief <i> [Deprecated] </i>
791 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
795 void ScrollToBottom(void);
799 * Scrolls to the top of the %CustomList.
801 * @brief <i> [Deprecated] </i>
802 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
806 void ScrollToTop(void);
810 * Scrolls to the item at the specified index. @n
811 * The specified item is drawn at the top of the %CustomList control.
813 * @brief <i> [Deprecated] </i>
814 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
817 * @return An error code
818 * @param[in] index The index of the %CustomList control item
819 * @exception E_SUCCESS The method is successful.
820 * @exception E_SYSTEM A system error has occurred.
821 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
822 * The specified @c index is less than @c 0 or greater than the item count.
825 result ScrollToTop(int index);
829 * Draws and shows the item at the specified index in the %CustomList control.
831 * @brief <i> [Deprecated] </i>
832 * @deprecated This class is deprecated. Instead of using this class, use ListView class.
835 * @return An error code
837 * @param[in] index The index of the %CustomList control item
838 * @exception E_SUCCESS The method is successful.
839 * @exception E_SYSTEM A system error has occurred.
840 * @exception E_INVALID_OPERATION The item has never been drawn before calling this method.
841 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
842 * The specified @c index is less than @c 0 or greater than the item count.
845 result RefreshItem(int index);
849 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
851 CustomList(const CustomList& rhs);
854 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
856 CustomList& operator =(const CustomList& rhs);
858 friend class _CustomListImpl;
862 }}} //Tizen::Ui::Controls
864 #endif // _FUI_CTRL_CUSTOM_LIST_H_