inc/FUiCtrlIGroupedListViewItemProvider.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18
  19 /**
  20  * @file        FUiCtrlIGroupedListViewItemProvider.h
  21  * @brief       This is the header file for the %IGroupedListViewItemProvider interface.
  22  *
  23  * This header file contains the declarations of the %IGroupedListViewItemProvider interface. @n
  24  * If an event is generated, a method of this class is called. @n
  25  * Therefore, if an application performs jobs related to the item events, it uses the methods of this class.
  26  *
  27  */
  28 #ifndef _FUI_CTRL_IGROUPED_LIST_VIEW_ITEM_PROVIDER_H_
  29 #define _FUI_CTRL_IGROUPED_LIST_VIEW_ITEM_PROVIDER_H_
  30
  31 #include <FUiCtrlGroupItem.h>
  32 #include <FUiCtrlListItemBase.h>
  33
  34 namespace Tizen {namespace Ui { namespace Controls
  35 {
  36
  37 /**
  38  * @interface   IGroupedListViewItemProvider
  39  * @brief               This interface implements the provider for the events generated by the %GroupedListView control.
  40  *
  41  * @since               2.0
  42  *
  43  * The %IGroupedListViewItemProvider interface is the interface for handling GroupedListView items.
  44  * The class that handles list items implements this interface, and the instance created using the GroupedListView's Construct()
  45  * method.
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_listviews.htm">ListViews</a>.
  48  */
  49 class _OSP_EXPORT_ IGroupedListViewItemProvider
  50 {
  51 // Operation
  52 public:
  53         /**
  54          * This polymorphic destructor should be overridden if required. @n
  55          * This way, the destructors of the derived classes are called
  56          * when the destructor of this interface is called.
  57          *
  58          * @since       2.0
  59          */
  60         virtual ~IGroupedListViewItemProvider(void) {}
  61
  62         /**
  63          * Gets the total number of groups.
  64          *
  65          * @since       2.0
  66          *
  67          * @return      The total number of groups
  68          * @remarks  This method must be implemented so that it returns the total number of groups in the GroupedListView control.
  69          */
  70         virtual int GetGroupCount(void) = 0;
  71
  72         /**
  73          * Gets the total number of items in the specified group.
  74          *
  75          * @since       2.0
  76          *
  77          * @return  The total number of items in the specified group
  78          * @param[in] groupIndex                The index of the group
  79          * @remarks  This method must be implemented so that it returns the total number of items for the specified group in the GroupedListView control.
  80          */
  81         virtual int GetItemCount(int groupIndex) = 0;
  82
  83         /**
  84          * Creates the group item for the specified index from the item provider.
  85          *
  86          * @since       2.0
  87          *
  88          * @return  A group item of the GroupedListView control
  89          * @param[in] groupIndex        The index of the group
  90          * @param[in] itemWidth         The width of the item
  91          * @remarks
  92          *                      - An application that uses the GroupedListView control must implement this method. This method is expected to return a group item that is
  93          *                      allocated on a heap memory.
  94          *                      - Note that when the item is not required, the GroupedListView control calls %IGroupedListViewItemProvider::DeleteGroupItem() and the
  95          *                      application deallocates the item.
  96          *                      - The returned item should not be a null pointer.
  97          */
  98         virtual Tizen::Ui::Controls::GroupItem* CreateGroupItem(int groupIndex, int itemWidth) = 0;
  99
 100         /**
 101          * Deletes the specified group item.
 102          *
 103          * @since       2.0
 104          *
 105          * @return  @c true if the item is deallocated by this method, @n
 106          *          else @c false
 107          * @param[in] groupIndex        The index of the group
 108          * @param[in] pItem             The pointer to GroupItem to delete
 109          * @param[in] itemWidth         The width of the item
 110          * @remarks
 111          *                      - An application that uses the %GroupedListView control must implement this method.
 112          *                      - Using this method, an application can deallocate the item.
 113          *                      - If an application deallocates the item, this method must return true. This notifies the GroupedListView control not to release the
 114          *                      item. Otherwise, the item is deallocated by the GroupedListView control.
 115          * @see     CreateItem()
 116          */
 117         virtual bool DeleteGroupItem(int groupIndex, Tizen::Ui::Controls::GroupItem* pItem, int itemWidth) = 0;
 118
 119         /**
 120          * Creates the specified item.
 121          *
 122          * @since       2.0
 123          *
 124          * @return      An item of the list
 125          * @param[in] groupIndex        The index of the group
 126          * @param[in] itemIndex         The index of the item
 127          * @param[in] itemWidth                 The width of the item
 128          * @remarks
 129          *                      - An application that uses the GroupedListView control must implement this method.
 130          *                      - This method is expected to return an item that is allocated on a heap memory.
 131          *                      - The returned item can be a simple or custom item.
 132          *                      - Note that when the item is not required, the GroupedListView control calls %IGroupedListViewItemProvider::DeleteItem() and the application
 133          *                      deallocates the item.
 134          * @see     DeleteItem()
 135          */
 136         virtual Tizen::Ui::Controls::ListItemBase* CreateItem(int groupIndex, int itemIndex, int itemWidth) = 0;
 137
 138         /**
 139          * Deletes the specified item.
 140          *
 141          * @since       2.0
 142          *
 143          * @return      @c true if the item is deallocated by this method, @n
 144          *                      else @c false
 145          * @param[in] groupIndex        The index of the group
 146          * @param[in] itemIndex         The index of the item
 147          * @param[in] pItem             The pointer to ListItemBase to delete
 148          * @param[in] itemWidth         The width of the item
 149          * @remarks
 150          *                      - An application that uses the GroupedListView control must implement this method.
 151          *                      - Using this method, an application can deallocate the item.
 152          *                      - If the application deallocates the item, this method must return true. This notifies the %GroupedListView control not to release the
 153          *                      item. Otherwise, the item is deallocated by the %GroupedListView control.
 154          * @see     CreateItem()
 155          */
 156         virtual bool DeleteItem(int groupIndex, int itemIndex, Tizen::Ui::Controls::ListItemBase* pItem, int itemWidth) = 0;
 157
 158         /**
 159          * Checks whether the item can be reordered.
 160          *
 161          * @since 2.0
 162          *
 163          * @return @c true if the item can be reordered, @n
 164          *              else @c false
 165          * @param[in] groupIndexFrom The source group index of the item
 166          * @param[in] groupIndexTo The target group index of the item
 167          */
 168         virtual bool IsReorderable(int groupIndexFrom, int groupIndexTo);
 169
 170 protected:
 171         //
 172         // The following methods are reserved and may change its name at any time without prior notice.
 173         //
 174         virtual void IGroupedListViewItemProvider_Reserved1(void) {}
 175         virtual void IGroupedListViewItemProvider_Reserved2(void) {}
 176         virtual void IGroupedListViewItemProvider_Reserved3(void) {}
 177 }; // IGroupedListViewItemProvider
 178
 179 }}} // Tizen::Ui::Controls
 180
 181 #endif // _FUI_CTRL_IGROUPED_LIST_VIEW_ITEM_PROVIDER_H_