inc/FUiCtrlIGroupedTableViewItemProvider.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 * @file FUiCtrlIGroupedTableViewItemProvider.h
  20 * @brief This is the header file for the %IGroupedTableViewItemProvider interface.
  21 *
  22 * This header file contains the declarations of the %IGroupedTableViewItemProvider interface.
  23 * If the event is generated, a method of this interface is called.
  24 * So, if applications do jobs related to item events, use the methods of this interface.
  25 *
  26 */
  27 #ifndef _FUI_CTRL_IGROUPED_TABLE_VIEW_ITEM_PROVIDER_H_
  28 #define _FUI_CTRL_IGROUPED_TABLE_VIEW_ITEM_PROVIDER_H_
  29
  30 namespace Tizen { namespace Ui { namespace Controls
  31 {
  32 class TableViewItem;
  33 class TableViewGroupItem;
  34
  35 /**
  36 * @interface IGroupedTableViewItemProvider
  37 * @brief  This interface implements the listener for events on %GroupedTableView.
  38 *
  39 * @since 2.0
  40 *
  41 * The %IGroupedTableViewItemProvider interface implements an item provider which generates items for GroupedTableView. %GroupedTableView calls the item provider
  42 * to request an item which is about to be displayed on a screen. Applications which use %GroupedTableView must implement the item provider.
  43 * The class is registered with a %GroupedTableView, using the GroupedTableView::SetItemProvider() method.
  44 */
  45 class _OSP_EXPORT_ IGroupedTableViewItemProvider
  46 {
  47 public:
  48         /**
  49         * This polymorphic destructor should be overridden if required.@n
  50         * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  51         *
  52         * @since 2.0
  53         */
  54         virtual ~IGroupedTableViewItemProvider(void) {}
  55
  56         /**
  57         * Gets the total number of groups.
  58         *
  59         * @since 2.0
  60         *
  61         * @return The total number of groups
  62         * @remarks  This method must be implemented so that it returns the total number of groups in the GroupedTableView control.
  63         */
  64         virtual int GetGroupCount(void) = 0;
  65
  66         /**
  67         * Gets the total number of items in the specified group.
  68         *
  69         * @since 2.0
  70         *
  71         * @return  The total number of items in the specified group
  72         * @param[in] groupIndex  The index of the group
  73         * @remarks  This method must be implemented so that it returns the total number of items for the specified group in the GroupedTableView control.
  74         */
  75         virtual int GetItemCount(int groupIndex) = 0;
  76
  77         /**
  78         * Gets the group item for the specified index from the item provider.
  79         *
  80         * @since 2.0
  81         *
  82         * @return  A group item of the GroupedTableView control
  83         * @param[in] groupIndex           The index of the group
  84         * @param[in] itemWidth            The width of the item
  85         * @remarks
  86         *                       - An application that uses the GroupedTableView control must implement this method. This method is expected to return a group item that is
  87         *                       allocated on a heap memory.
  88         *                       - Note that when the group item is not required, the %GroupedTableView control calls IGroupedTableViewItemProvider::DeleteGroupItem() and the
  89         *                       application deallocates the item.
  90         *                       - The returned item should not be a null pointer.
  91         */
  92         virtual TableViewGroupItem* CreateGroupItem(int groupIndex, int itemWidth) = 0;
  93
  94         /**
  95         * Deletes the specified group item.
  96         *
  97         * @since 2.0
  98         *
  99         * @return  @c true if the group item is deallocated by this method,
 100         *          else @c false
 101         * @param[in] groupIndex        The index of the group
 102         * @param[in] pItem             The pointer to TableViewGroupItem to delete
 103         * @remarks
 104         *                       - An application that uses the GroupedTableView control must implement this method.
 105         *                       - Using this method, an application can deallocate the item.
 106         *                       - If an application deallocates the item, this method must return @c true. This notifies the %GroupedTableView control not to release the
 107         *                       item. Otherwise, the item is deallocated by the %GroupedTableView control.
 108         * @see     CreateGroupItem()
 109         */
 110         virtual bool DeleteGroupItem(int groupIndex, TableViewGroupItem* pItem) = 0;
 111
 112         /**
 113         * Updates the specified group item.
 114         *
 115         * @since 2.0
 116         *
 117         * @param[in] groupIndex           The group index
 118         * @param[in] pItem                The pointer to TableViewGroupItem to update
 119         * @remarks
 120         *                       - An application that uses the GroupedTableView control must implement this method.
 121         *                       - This method is called when the modification of a group item is requested.
 122         *                       - The application can change @c pItem in this method, but should not keep @c pItem for later use.
 123         */
 124         virtual void UpdateGroupItem(int groupIndex, TableViewGroupItem* pItem) = 0;
 125
 126         /**
 127         * Creates the specified item.
 128         *
 129         * @since 2.0
 130         *
 131         * @return An item of the GroupedTableView
 132         * @param[in] groupIndex           The group index
 133         * @param[in] itemIndex            The item index
 134         * @param[in] itemWidth            The width of the item
 135         * @remarks
 136         *                       - An application that uses the GroupedTableView control must implement this method.
 137         *                       - This method is expected to return an item that is allocated on a heap memory.
 138         *                       - The returned item can be a simple or custom item.
 139         *                       - Note that when the item is not required, the %GroupedTableView control calls IGroupedTableViewItemProvider::DeleteItem()
 140         *                       and the application deallocates the item.
 141         * @see     DeleteItem()
 142         */
 143         virtual TableViewItem* CreateItem(int groupIndex, int itemIndex, int itemWidth) = 0;
 144
 145         /**
 146         * Deletes the specified item.
 147         *
 148         * @since 2.0
 149         *
 150         * @return @c true if the item is deallocated by this method, @n
 151         *   else @c false
 152         * @param[in] groupIndex           The group index
 153         * @param[in] itemIndex            The item index
 154         * @param[in] pItem                The pointer to TableViewItem to delete
 155         * @remarks
 156         *                       - An application that uses the GroupedTableView control must implement this method.
 157         *                       - Using this method, an application can deallocate the item.
 158         *                       - If the application deallocates the item, this method must return @c true. This notifies the %GroupedTableView control not to release the
 159         *                       item. Otherwise, the item is deallocated by the %GroupedTableView control.
 160         * @see     CreateItem()
 161         */
 162         virtual bool DeleteItem(int groupIndex, int itemIndex, TableViewItem* pItem) = 0;
 163
 164         /**
 165         * Updates the specified item.
 166         *
 167         * @since 2.0
 168         *
 169         * @param[in] groupIndex                     The group index
 170         * @param[in] itemIndex            The item index
 171         * @param[in] pItem                            The pointer to TableViewItem to update
 172         * @remarks
 173         *                       - An application that uses the GroupedTableView control must implement this method.
 174         *                       - This method is called when the modification of an item is requested.
 175         *                       - The application can change @c pItem in this method, but should not keep @c pItem for later use.
 176         */
 177         virtual void UpdateItem(int groupIndex, int itemIndex, TableViewItem* pItem) = 0;
 178
 179         /**
 180         * Gets the default height of a group item.
 181         *
 182         * @since 2.0
 183         *
 184         * @return  The default height of a group item
 185         * @remarks This method must be implemented so that it returns the default height of group items in the GroupedTableView control.
 186         */
 187         virtual int GetDefaultGroupItemHeight(void) = 0;
 188
 189
 190         /**
 191         * Gets the default height of an item.
 192         *
 193         * @since 2.0
 194         *
 195         * @return  The default height of an item
 196         * @remarks This method must be implemented so that it returns the default height of items in the GroupedTableView control.
 197         */
 198         virtual int GetDefaultItemHeight(void) = 0;
 199
 200         /**
 201         * Checks whether the item can be reordered.
 202         *
 203         * @since 2.1
 204         *
 205         * @return              @c true if the item can be reordered, @n
 206         *                                       else @c false
 207         * @param[in]       groupIndexFrom The source group index of the item
 208         * @param[in]       groupIndexTo The target group index of the item
 209         */
 210         virtual bool IsReorderable(int groupIndexFrom, int groupIndexTo) { return false; }
 211
 212 protected:
 213         //
 214         // This method is for internal use only. Using this method can cause behavioral, security-related,
 215         // and consistency-related issues in the application.
 216         //
 217         // This method is reserved and may change its name at any time without prior notice.
 218         //
 219         // @since 2.0
 220         //
 221         virtual void IGroupedTableViewItemProvider_Reserved1(void) {}
 222
 223         //
 224         // This method is for internal use only. Using this method can cause behavioral, security-related,
 225         // and consistency-related issues in the application.
 226         //
 227         // This method is reserved and may change its name at any time without prior notice.
 228         //
 229         // @since 2.0
 230         //
 231         virtual void IGroupedTableViewItemProvider_Reserved2(void) {}
 232
 233 }; // IGroupedTableViewItemProvider
 234
 235 }}} // Tizen::Ui::Controls
 236
 237 #endif // _FUI_CTRL_IGROUPED_TABLE_VIEW_ITEM_PROVIDER_H_