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