| Conforms to | |
| Framework | /System/Library/Frameworks/UIKit.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Companion guide | |
| Declared in | UITableView.h |
| Related sample code |
The delegate of a UITableView object must adopt the UITableViewDelegate protocol. Optional methods of the protocol allow the delegate to manage selections, configure section headings and footers, help to delete and reorder cells, and perform other actions.
Many methods of UITableViewDelegate take NSIndexPath objects as parameters and return values. UITableView declares a category on NSIndexPath that enables you to get the represented row index (row property) and section index (section property), and to construct an index path from a given row index and section index (indexPathForRow:inSection: method). Because rows are located within their sections, you usually must evaluate the section index number before you can identify the row by its index number.
– tableView:heightForRowAtIndexPath:
– tableView:indentationLevelForRowAtIndexPath:
– tableView:willDisplayCell:forRowAtIndexPath:
– tableView:accessoryButtonTappedForRowWithIndexPath:
– tableView:accessoryTypeForRowWithIndexPath: Deprecated in iPhone OS 3.0
– tableView:willSelectRowAtIndexPath:
– tableView:didSelectRowAtIndexPath:
– tableView:willDeselectRowAtIndexPath:
– tableView:didDeselectRowAtIndexPath:
– tableView:viewForHeaderInSection:
– tableView:viewForFooterInSection:
– tableView:heightForHeaderInSection:
– tableView:heightForFooterInSection:
– tableView:willBeginEditingRowAtIndexPath:
– tableView:didEndEditingRowAtIndexPath:
– tableView:editingStyleForRowAtIndexPath:
– tableView:titleForDeleteConfirmationButtonForRowAtIndexPath:
– tableView:shouldIndentWhileEditingRowAtIndexPath:
Tells the delegate that the user tapped the accessory (disclosure) view associated with a given row.
- (void)tableView:(UITableView *)tableView accessoryButtonTappedForRowWithIndexPath:(NSIndexPath *)indexPath
The table-view object informing the delegate of this event.
An index path locating the row in tableView.
The delegate usually responds to the tap on the disclosure button (the accessory view) by displaying a new view related to the selected row.
UITableView.hTells the delegate that the specified row is now deselected.
- (void)tableView:(UITableView *)tableView didDeselectRowAtIndexPath:(NSIndexPath *)indexPath
A table-view object informing the delegate about the row deselection.
An index path locating the deselected row in tableView.
The delegate handles row deselections in this method. It could, for example, remove the check-mark image (UITableViewCellAccessoryCheckmark) associated with the row.
UITableView.hTells the delegate that the table view has left editing mode.
- (void)tableView:(UITableView *)tableView didEndEditingRowAtIndexPath:(NSIndexPath *)indexPath
The table-view object providing this information.
An index path locating the row in tableView.
This method is called when the table view exits editing mode after having been put into the mode by the user swiping across the row identified by indexPath. As a result, a Delete button appears in the row; however, in this "swipe to delete" mode the table view does not display any insertion, deletion, and reordering controls. When entering this "swipe to delete" editing mode, the table view sends a tableView:willBeginEditingRowAtIndexPath: message to the delegate to allow it to adjust its user interface.
UITableView.hTells the delegate that the specified row is now selected.
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
A table-view object informing the delegate about the new row selection.
An index path locating the new selected row in tableView.
The delegate handles selections in this method. One of the things it can do is exclusively assign the check-mark image (UITableViewCellAccessoryCheckmark) to one row in a section (radio-list style). This method isn’t called when the editing property of the table is set to YES (that is, the table view is in editing mode). See "Managing Selections" in Table View Programming Guide for iPhone OS for further information (and code examples) related to this method.
UITableView.hAsks the delegate for the editing style of a row at a particular location in a table view.
- (UITableViewCellEditingStyle)tableView:(UITableView *)tableView editingStyleForRowAtIndexPath:(NSIndexPath *)indexPath
The table-view object requesting this information.
An index path locating a row in tableView.
The editing style of the cell for the row identified by indexPath.
This method allows the delegate to customize the editing style of the cell located atindexPath. If the delegate does not implement this method and the UITableViewCell object is editable (that is, it has its editing property set to YES), the cell has the UITableViewCellEditingStyleDelete style set for it.
UITableView.hAsks the delegate for the height to use for the footer of a particular section.
- (CGFloat)tableView:(UITableView *)tableView heightForFooterInSection:(NSInteger)section
The table-view object requesting this information.
An index number identifying a section of tableView .
A floating-point value that specifies the height (in points) of the footer for section.
This method allows the delegate to specify section footers with varying heights. The table view does not call this method if it was created in a plain style (UITableViewStylePlain).
– tableView:targetIndexPathForMoveFromRowAtIndexPath:toProposedIndexPath:– tableView:viewForFooterInSection:UITableView.hAsks the delegate for the height to use for the header of a particular section.
- (CGFloat)tableView:(UITableView *)tableView heightForHeaderInSection:(NSInteger)section
The table-view object requesting this information.
An index number identifying a section of tableView .
A floating-point value that specifies the height (in points) of the header for section.
This method allows the delegate to specify section headers with varying heights.
UITableView.hAsks the delegate for the height to use for a row in a specified location.
- (CGFloat)tableView:(UITableView *)tableView heightForRowAtIndexPath:(NSIndexPath *)indexPath
The table-view object requesting this information.
An index path that locates a row in tableView.
A floating-point value that specifies the height (in points) that row should be.
The method allows the delegate to specify rows with varying heights. If this method is implemented, the value it returns overrides the value specified for the rowHeight property of UITableView for the given row.
There are performance implications to using tableView:heightForRowAtIndexPath: instead of the rowHeight property. Every time a table view is displayed, it calls tableView:heightForRowAtIndexPath: on the delegate for each of its rows, which can result in a significant performance problem with table views having a large number of rows (approximately 1000 or more).
Important: Due to an underlying implementation detail, you should not return values greater than 2009.
UITableView.hAsks the delegate to return the level of indentation for a row in a given section.
- (NSInteger)tableView:(UITableView *)tableView indentationLevelForRowAtIndexPath:(NSIndexPath *)indexPath
The table-view object requesting this information.
An index path locating the row in tableView.
Returns the depth of the specified row to show its hierarchical position in the section.
UITableView.hAsks the delegate whether the background of the specified row should be indented while the table view is in editing mode.
- (BOOL)tableView:(UITableView *)tableView shouldIndentWhileEditingRowAtIndexPath:(NSIndexPath *)indexPath
The table-view object requesting this information.
An index-path object locating the row in its section.
YES if the background of the row should be indented, otherwise NO.
If the delegate does not implement this method, the default is YES. This method is unrelated to tableView:indentationLevelForRowAtIndexPath:.
UITableView.hAsks the delegate to return a new index path to retarget a proposed move of a row.
- (NSIndexPath *)tableView:(UITableView *)tableView targetIndexPathForMoveFromRowAtIndexPath:(NSIndexPath *)sourceIndexPath toProposedIndexPath:(NSIndexPath *)proposedDestinationIndexPath
The table-view object that is requesting this information.
An index-path object identifying the original location of a row (in its section) that is being dragged.
An index-path object identifying the currently proposed destination of the row being dragged.
An index-path object locating the desired row destination for the move operation. Return proposedDestinationIndexPath if that location is suitable.
This method allows customization of the target row for a particular row as it is being moved up and down a table view. As the dragged row hovers over a another row, the destination row slides downward to visually make room for the relocation; this is the location identified by proposedDestinationIndexPath.
UITableView.hChanges the default title of the delete-confirmation button.
- (NSString *)tableView:(UITableView *)tableView titleForDeleteConfirmationButtonForRowAtIndexPath:(NSIndexPath *)indexPath
The table-view object requesting this information.
An index-path object locating the row in its section.
A localized string to used as the title of the delete-confirmation button.
By default, the delete-confirmation button, which appears on the right side of the cell, has the title of “Delete”. The table view displays this button when the user attempts to delete a row, either by swiping the row or tapping the red minus icon in editing mode or ). You can implement this method to return an alternative title, which should be localized.
UITableView.hAsks the delegate for a view object to display in the footer of the specified section of the table view.
- (UIView *)tableView:(UITableView *)tableView viewForFooterInSection:(NSInteger)section
The table-view object asking for the view object.
An index number identifying a section of tableView .
A view object to be displayed in the footer of section .
The returned object, for example, can be a UILabel or UIImageView object. The table view automatically adjusts the height of the section footer to accommodate the returned view object. The table view does not call this method if it was created in a plain style (UITableViewStylePlain).
– tableView:targetIndexPathForMoveFromRowAtIndexPath:toProposedIndexPath:– tableView:heightForFooterInSection:UITableView.hAsks the delegate for a view object to display in the header of the specified section of the table view.
- (UIView *)tableView:(UITableView *)tableView viewForHeaderInSection:(NSInteger)section
The table-view object asking for the view object.
An index number identifying a section of tableView .
A view object to be displayed in the header of section .
The returned object, for example, can be a UILabel or UIImageView object. The table view automatically adjusts the height of the section header to accommodate the returned view object. The table view calls this method even if it was created in a plain style (UITableViewStylePlain). This method only works correctly when tableView:heightForHeaderInSection: is also implemented.
UITableView.hTells the delegate that the table view is about to go into editing mode.
- (void)tableView:(UITableView *)tableView willBeginEditingRowAtIndexPath:(NSIndexPath *)indexPath
The table-view object providing this information.
An index path locating the row in tableView.
This method is called when the user swipes horizontally across a row; as a consequence, the table view sets its editing property to YES (thereby entering editing mode) and displays a Delete button in the row identified by indexPath. In this "swipe to delete" mode the table view does not display any insertion, deletion, and reordering controls. This method gives the delegate an opportunity to adjust the application's user interface to editing mode. When the table exits editing mode (for example, the user taps the Delete button), the table view calls tableView:didEndEditingRowAtIndexPath:.
tableView:commitEditingStyle:forRowAtIndexPath: method.UITableView.hTells the delegate that a specified row is about to be deselected.
- (NSIndexPath *)tableView:(UITableView *)tableView willDeselectRowAtIndexPath:(NSIndexPath *)indexPath
A table-view object informing the delegate about the impending deselection.
An index path locating the row in tableView to be deselected.
An index-path object that confirms or alters the deselected row. Return an NSIndexPath object other than indexPath if you want another cell to be deselected. Return nil if you don’t want the row deselected.
This method is only called if there is an existing selection when the user tries to select a different row. The delegate is sent this method for the previously selected row. You can use UITableViewCellSelectionStyleNone to disable the appearance of the cell highlight on touch-down.
UITableView.hTells the delegate the table view is about to draw a cell for a particular row.
- (void)tableView:(UITableView *)tableView willDisplayCell:(UITableViewCell *)cell forRowAtIndexPath:(NSIndexPath *)indexPath
The table-view object informing the delegate of this impending event.
A table-view cell object that tableView is going to use when drawing the row.
An index path locating the row in tableView.
A table view sends this message to its delegate just before it uses cell to draw a row, thereby permitting the delegate to customize the cell object before it is displayed. This method gives the delegate a chance to override state-based properties set earlier by the table view, such as selection and background color. After the delegate returns, the table view sets only the alpha and frame properties, and then only when animating rows as they slide in or out.
– tableView:cellForRowAtIndexPath: (UITableViewDataSource)– prepareForReuse (UITableViewCell)UITableView.hTells the delegate that a specified row is about to be selected.
- (NSIndexPath *)tableView:(UITableView *)tableView willSelectRowAtIndexPath:(NSIndexPath *)indexPath
A table-view object informing the delegate about the impending selection.
An index path locating the row in tableView.
An index-path object that confirms or alters the selected row. Return an NSIndexPath object other than indexPath if you want another cell to be selected. Return nil if you don't want the row selected.
This method is not called until users touch a row and then lift their finger; the row isn't selected until then, although it is highlighted on touch-down. You can use UITableViewCellSelectionStyleNone to disable the appearance of the cell highlight on touch-down. This method isn’t called when the editing property of the table is set to YES (that is, the table view is in editing mode).
– tableView:didSelectRowAtIndexPath:– tableView:shouldIndentWhileEditingRowAtIndexPath:– tableView:willDeselectRowAtIndexPath:UITableView.hLast updated: 2009-11-17
iPhone OS Reference Library User Experience: Tables UITableViewDelegate Protocol Reference