inc/FUiCtrlITableViewItemProvider.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 FUiCtrlITableViewItemProvider.h
  20 * @brief This is the header file for the %ITableViewItemProvider interface.
  21 *
  22 * This header file contains the declarations of the %ITableViewItemProvider 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
  28 #ifndef _FUI_CTRL_ITABLE_VIEW_ITEM_PROVIDER_H_
  29 #define _FUI_CTRL_ITABLE_VIEW_ITEM_PROVIDER_H_
  30
  31 namespace Tizen { namespace Ui { namespace Controls
  32 {
  33 class TableViewItem;
  34
  35 /**
  36 * @interface ITableViewItemProvider
  37 * @brief  This interface implements the listener for events on %TableView.
  38 *
  39 * @since 2.0
  40 *
  41 * The %ITableViewItemProvider interface implements an item provider which generates items for TableView. %TableView calls the item provider
  42 * to request an item which is about to be displayed on a screen. Applications which use %TableView must implement the item provider.
  43 * The class is registered with a %TableView, using the TableView::SetItemProvider() method.
  44 */
  45 class _OSP_EXPORT_ ITableViewItemProvider
  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 ~ITableViewItemProvider(void) {}
  55
  56         /**
  57         * Gets the total number of items in the specified group.
  58         *
  59         * @since 2.0
  60         *
  61         * @return  The total number of items
  62         * @remarks This method must be implemented so that it returns the total number of items for the specified group in the TableView control.
  63         */
  64         virtual int GetItemCount(void) = 0;
  65
  66         /**
  67         * Creates the specified item.
  68         *
  69         * @since 2.0
  70         *
  71         * @return An item of the TableView
  72         * @param[in] itemIndex  The item index
  73         * @param[in] itemWidth The width of the item
  74         * @remarks
  75         *                       - An application that uses the TableView control must implement this method.
  76         *                       - This method is expected to return an item that is allocated on a heap memory.
  77         *                       - The returned item can be a %TableViewItem or a class derived from TableViewItem.
  78         *                       - The returned item should not be a null pointer.
  79         *                       - Note that when the item is not required, the %TableView control calls ITableViewItemProvider::DeleteItem(),
  80         *                       allowing the application to deallocate the item.
  81         * @see           DeleteItem()
  82         */
  83         virtual TableViewItem* CreateItem(int itemIndex, int itemWidth) = 0;
  84
  85         /**
  86         * Deletes the specified item.
  87         *
  88         * @since 2.0
  89         *
  90         * @return @c true if the item is deallocated by this method, @n
  91         *         else @c false
  92         * @param[in] itemIndex The item index
  93         * @param[in] pItem The pointer to TableViewItem to delete
  94         * @remarks
  95         *                       - An application that uses the TableView control must implement this method.
  96         *                       - Using this method, an application can deallocate the item.
  97         *                       - If the application deallocates the item, this method must return @c true. This notifies the %TableView not to release the
  98         *                       item. Otherwise, the item is deallocated by the %TableView.
  99         * @see     CreateItem()
 100         */
 101         virtual bool DeleteItem(int itemIndex, TableViewItem* pItem) = 0;
 102
 103         /**
 104         * Updates the specified item.
 105         *
 106         * @since 2.0
 107         *
 108         * @param[in] itemIndex  The item index
 109         * @param[in] pItem The pointer to TableViewItem to update
 110         * @remarks
 111         *                       - An application that uses the TableView control must implement this method.
 112         *                       - This method is called when the modification of an item is requested.
 113         *                       - The application can change @c pItem in this method, but should not keep @c pItem for later use.
 114         */
 115         virtual void UpdateItem(int itemIndex, TableViewItem* pItem) = 0;
 116
 117         /**
 118         * Gets the default height of an item.
 119         *
 120         * @since 2.0
 121         *
 122         * @return  The default height of an item
 123         * @remarks This method must be implemented so that it returns the default height of items in the TableView control.
 124         */
 125         virtual int GetDefaultItemHeight(void) = 0;
 126
 127 protected:
 128         //
 129         // This method is for internal use only. Using this method can cause behavioral, security-related,
 130         // and consistency-related issues in the application.
 131         //
 132         // This method is reserved and may change its name at any time without prior notice.
 133         //
 134         // @since 2.0
 135         //
 136         virtual void ITableViewItemProvider_Reserved1(void) {}
 137
 138         //
 139         // This method is for internal use only. Using this method can cause behavioral, security-related,
 140         // and consistency-related issues in the application.
 141         //
 142         // This method is reserved and may change its name at any time without prior notice.
 143         //
 144         // @since 2.0
 145         //
 146         virtual void ITableViewItemProvider_Reserved2(void) {}
 147
 148         //
 149         // This method is for internal use only. Using this method can cause behavioral, security-related,
 150         // and consistency-related issues in the application.
 151         //
 152         // This method is reserved and may change its name at any time without prior notice.
 153         //
 154         // @since 2.0
 155         //
 156         virtual void ITableViewItemProvider_Reserved3(void) {}
 157 }; // ITableViewItemProvider
 158
 159 }}} // Tizen::Ui::Controls
 160
 161 #endif // _FUI_CTRL_ITABLE_VIEW_ITEM_PROVIDER_H_