Protocol: UITableViewDelegate

Overview

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.Tells the delegate that the user tapped the accessory (disclosure) view associated with a given row.Asks the delegate if the editing menu should omit the Copy or Paste command for a given row. Tells the delegate that the specified row is now deselected.Tells the delegate that the specified cell was removed from the table.Tells the delegate that the specified footer view was removed from the table.Tells the delegate that the specified header view was removed from the table.Tells the delegate that the table view has left editing mode.Tells the delegate that the specified row was highlighted.Tells the delegate that the specified row is now selected.Tells the delegate that the highlight was removed from the row at the specified index path.Asks the delegate for the editing style of a row at a particular location in a table view.Asks the delegate for the height to use for the footer of a particular section.Asks the delegate for the height to use for the header of a particular section.Asks the delegate for the height to use for a row in a specified location.Asks the delegate to return the level of indentation for a row in a given section.Tells the delegate to perform a copy or paste operation on the content of a given row.Asks the delegate if the specified row should be highlighted.Asks the delegate whether the background of the specified row should be indented while the table view is in editing mode.Asks the delegate if the editing menu should be shown for a certain row.Asks the delegate to return a new index path to retarget a proposed move of a row.Changes the default title of the delete-confirmation button.Asks the delegate for a view object to display in the footer of the specified section of the table view.Asks the delegate for a view object to display in the header of the specified section of the table view.Tells the delegate that the table view is about to go into editing mode.Tells the delegate that a specified row is about to be deselected.Tells the delegate the table view is about to draw a cell for a particular row.Tells the delegate that a footer view is about to be displayed for the specified section.Tells the delegate that a header view is about to be displayed for the specified section.Tells the delegate that a specified row is about to be selected.

Instance Method Summary (collapse)

Instance Method Details

- (Object) tableView(tableView, accessoryButtonTappedForRowWithIndexPath:indexPath)

Tells the delegate that the user tapped the accessory (disclosure) view associated with a given row. The delegate usually responds to the tap on the disclosure button (the accessory view) by displaying a new view related to the selected row. This method is not called when an accessory view is set for the row at indexPath.

Parameters:

  • tableView (UITableView) —

    The table-view object informing the delegate of this event.

  • indexPath (NSIndexPath) —

    An index path locating the row in tableView.

Returns:

- (Boolean) tableView(tableView, canPerformAction:action, forRowAtIndexPath:indexPath, withSender:sender)

Asks the delegate if the editing menu should omit the Copy or Paste command for a given row. This method is invoked after tableView:shouldShowMenuForRowAtIndexPath:. It gives the developer the opportunity to exclude one of the commands—Copy or Paste—from the editing menu. For example, the user might have copied some cell content from one row but wants to paste into another row that doesn’t take the copied content. In a case like this, return NO from this method.

Parameters:

  • tableView (UITableView) —

    The table-view object that is making this request.

  • action (Symbol) —

    A selector type identifying the copy: or paste: method of the UIResponderStandardEditActions informal protocol.

  • indexPath (NSIndexPath) —

    An index-path object locating the row in its section.

  • sender (Object) —

    The object that initially sent the copy: or paste: message. T

Returns:

  • (Boolean) —

    YES if the command corresponding to action should appear in the editing menu, otherwise NO. The default value is NO.

- (Object) tableView(tableView, didDeselectRowAtIndexPath:indexPath)

Tells the delegate that the specified row is now deselected. The delegate handles row deselections in this method. It could, for example, remove the check-mark image (UITableViewCellAccessoryCheckmark) associated with the row.

Parameters:

  • tableView (UITableView) —

    A table-view object informing the delegate about the row deselection.

  • indexPath (NSIndexPath) —

    An index path locating the deselected row in tableView.

Returns:

- (Object) tableView(tableView, didEndDisplayingCell:cell, forRowAtIndexPath:indexPath)

Tells the delegate that the specified cell was removed from the table. Use this method to detect when a cell is removed from a table view, as opposed to monitoring the view itself to see when it appears or disappears.

Parameters:

Returns:

- (Object) tableView(tableView, didEndDisplayingFooterView:view, forSection:section)

Tells the delegate that the specified footer view was removed from the table. Use this method to detect when a footer view is removed from a table view, as opposed to monitoring the view itself to see when it appears or disappears.

Parameters:

  • tableView (UITableView) —

    The table-view object that removed the view.

  • view (UIView) —

    The footer view that was removed.

  • section (Integer) —

    The index of the section that contained the footer.

Returns:

- (Object) tableView(tableView, didEndDisplayingHeaderView:view, forSection:section)

Tells the delegate that the specified header view was removed from the table. Use this method to detect when a header view is removed from a table view, as opposed to monitoring the view itself to see when it appears or disappears.

Parameters:

  • tableView (UITableView) —

    The table-view object that removed the view.

  • view (UIView) —

    The header view that was removed.

  • section (Integer) —

    The index of the section that contained the header.

Returns:

- (Object) tableView(tableView, didEndEditingRowAtIndexPath:indexPath)

Tells the delegate that the table view has left editing mode. 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.

Parameters:

  • tableView (UITableView) —

    The table-view object providing this information.

  • indexPath (NSIndexPath) —

    An index path locating the row in tableView.

Returns:

- (Object) tableView(tableView, didHighlightRowAtIndexPath:indexPath)

Tells the delegate that the specified row was highlighted.

Parameters:

  • tableView (UITableView) —

    The table-view object that highlighted the cell.

  • indexPath (NSIndexPath) —

    The index path of the row that was highlighted.

Returns:

- (Object) tableView(tableView, didSelectRowAtIndexPath:indexPath)

Tells the delegate that the specified row is now selected. 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 iOS for further information (and code examples) related to this method.

Parameters:

  • tableView (UITableView) —

    A table-view object informing the delegate about the new row selection.

  • indexPath (NSIndexPath) —

    An index path locating the new selected row in tableView.

Returns:

- (Object) tableView(tableView, didUnhighlightRowAtIndexPath:indexPath)

Tells the delegate that the highlight was removed from the row at the specified index path.

Parameters:

  • tableView (UITableView) —

    The table-view object that removed the highlight from the cell.

  • indexPath (NSIndexPath) —

    The index path of the row that had its highlight removed.

Returns:

- (UITableViewCellEditingStyle) tableView(tableView, editingStyleForRowAtIndexPath:indexPath)

Asks the delegate for the editing style of a row at a particular location in a table view. 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.

Parameters:

  • tableView (UITableView) —

    The table-view object requesting this information.

  • indexPath (NSIndexPath) —

    An index path locating a row in tableView.

Returns:

- (Float) tableView(tableView, heightForFooterInSection:section)

Asks the delegate for the height to use for the footer of a particular 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).

Parameters:

  • tableView (UITableView) —

    The table-view object requesting this information.

  • section (Integer) —

    An index number identifying a section of tableView .

Returns:

  • (Float) —

    A floating-point value that specifies the height (in points) of the footer for section.

- (Float) tableView(tableView, heightForHeaderInSection:section)

Asks the delegate for the height to use for the header of a particular section. This method allows the delegate to specify section headers with varying heights.

Parameters:

  • tableView (UITableView) —

    The table-view object requesting this information.

  • section (Integer) —

    An index number identifying a section of tableView .

Returns:

  • (Float) —

    A floating-point value that specifies the height (in points) of the header for section.

- (Float) tableView(tableView, heightForRowAtIndexPath:indexPath)

Asks the delegate for the height to use for a row in a specified location. 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.

Parameters:

  • tableView (UITableView) —

    The table-view object requesting this information.

  • indexPath (NSIndexPath) —

    An index path that locates a row in tableView.

Returns:

  • (Float) —

    A floating-point value that specifies the height (in points) that row should be.

- (Integer) tableView(tableView, indentationLevelForRowAtIndexPath:indexPath)

Asks the delegate to return the level of indentation for a row in a given section.

Parameters:

  • tableView (UITableView) —

    The table-view object requesting this information.

  • indexPath (NSIndexPath) —

    An index path locating the row in tableView.

Returns:

  • (Integer) —

    Returns the depth of the specified row to show its hierarchical position in the section.

- (Object) tableView(tableView, performAction:action, forRowAtIndexPath:indexPath, withSender:sender)

Tells the delegate to perform a copy or paste operation on the content of a given row. The table view invokes this method for a given action if the user taps Copy or Paste in the editing menu. The delegate can do whatever is appropriate for the action; for example, for a copy, it can extract the relevant cell content for the row at indexPath and write it to the general pasteboard or an application (private) pasteboard. See UIPasteboard Class Reference for further information.

Parameters:

  • tableView (UITableView) —

    The table-view object that is making this request.

  • action (Symbol) —

    A selector type identifying the copy: or paste: method of the UIResponderStandardEditActions informal protocol.

  • indexPath (NSIndexPath) —

    An index-path object locating the row in its section.

  • sender (Object) —

    The object that initially sent the copy: or paste: message.

Returns:

- (Boolean) tableView(tableView, shouldHighlightRowAtIndexPath:indexPath)

Asks the delegate if the specified row should be highlighted. As touch events arrive, the table view highlights rows in anticipation of the user selecting them. As it processes those touch events, the table view calls this method to ask your delegate if a given cell should be highlighted. Your delegate can implement this method and use it to prevent the highlighting of a row when another row is already selected or when other relevant criteria occur.If you do not implement this method, the default return value is YES.

Parameters:

  • tableView (UITableView) —

    The table-view object that is making this request.

  • indexPath (NSIndexPath) —

    The index path of the row being highlighted.

Returns:

  • (Boolean) —

    YES if the row should be highlighted or NO if it should not.

- (Boolean) tableView(tableView, shouldIndentWhileEditingRowAtIndexPath:indexPath)

Asks the delegate whether the background of the specified row should be indented while the table view is in editing mode. If the delegate does not implement this method, the default is YES. This method is unrelated to tableView:indentationLevelForRowAtIndexPath:.

Parameters:

  • tableView (UITableView) —

    The table-view object requesting this information.

  • indexPath (NSIndexPath) —

    An index-path object locating the row in its section.

Returns:

  • (Boolean) —

    YES if the background of the row should be indented, otherwise NO.

- (Boolean) tableView(tableView, shouldShowMenuForRowAtIndexPath:indexPath)

Asks the delegate if the editing menu should be shown for a certain row. If the user tap-holds a certain row in the table view, this method (if implemented) is invoked first. Return NO if the editing menu shouldn’t be shown—for example, the cell corresponding to the row contains content that shouldn’t be copied or pasted over.

Parameters:

  • tableView (UITableView) —

    The table-view object that is making this request.

  • indexPath (NSIndexPath) —

    An index-path object locating the row in its section.

Returns:

  • (Boolean) —

    YES if the editing menu should be shown positioned near the row and pointing to it, otherwise NO. The default value is NO.

- (NSIndexPath) tableView(tableView, targetIndexPathForMoveFromRowAtIndexPath:sourceIndexPath, toProposedIndexPath:proposedDestinationIndexPath)

Asks the delegate to return a new index path to retarget a proposed move of a row. 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.

Parameters:

  • tableView (UITableView) —

    The table-view object that is requesting this information.

  • sourceIndexPath (NSIndexPath) —

    An index-path object identifying the original location of a row (in its section) that is being dragged.

  • proposedDestinationIndexPath (NSIndexPath) —

    An index-path object identifying the currently proposed destination of the row being dragged.

Returns:

  • (NSIndexPath) —

    An index-path object locating the desired row destination for the move operation. Return proposedDestinationIndexPath if that location is suitable.

- (String) tableView(tableView, titleForDeleteConfirmationButtonForRowAtIndexPath:indexPath)

Changes the default 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. You can implement this method to return an alternative title, which should be localized.

Parameters:

  • tableView (UITableView) —

    The table-view object requesting this information.

  • indexPath (NSIndexPath) —

    An index-path object locating the row in its section.

Returns:

  • (String) —

    A localized string to used as the title of the delete-confirmation button.

- (UIView) tableView(tableView, viewForFooterInSection:section)

Asks the delegate for a view object to display in the footer of the specified section of the table view. The returned object can be a UILabel or UIImageView object, as well as a custom view. This method only works correctly when tableView:heightForFooterInSection: is also implemented.

Parameters:

  • tableView (UITableView) —

    The table-view object asking for the view object.

  • section (Integer) —

    An index number identifying a section of tableView .

Returns:

  • (UIView) —

    A view object to be displayed in the footer of section .

- (UIView) tableView(tableView, viewForHeaderInSection:section)

Asks the delegate for a view object to display in the header of the specified section of the table view. The returned object can be a UILabel or UIImageView object, as well as a custom view. This method only works correctly when tableView:heightForHeaderInSection: is also implemented.

Parameters:

  • tableView (UITableView) —

    The table-view object asking for the view object.

  • section (Integer) —

    An index number identifying a section of tableView .

Returns:

  • (UIView) —

    A view object to be displayed in the header of section .

- (Object) tableView(tableView, willBeginEditingRowAtIndexPath:indexPath)

Tells the delegate that the table view is about to go into editing mode. 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:.Note: A swipe motion across a cell does not cause the display of a Delete button unless the table view’€™s data source implements the tableView:commitEditingStyle:forRowAtIndexPath: method.

Parameters:

  • tableView (UITableView) —

    The table-view object providing this information.

  • indexPath (NSIndexPath) —

    An index path locating the row in tableView.

Returns:

- (NSIndexPath) tableView(tableView, willDeselectRowAtIndexPath:indexPath)

Tells the delegate that a specified row is about to be 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.

Parameters:

  • tableView (UITableView) —

    A table-view object informing the delegate about the impending deselection.

  • indexPath (NSIndexPath) —

    An index path locating the row in tableView to be deselected.

Returns:

  • (NSIndexPath) —

    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.

- (Object) tableView(tableView, willDisplayCell:cell, forRowAtIndexPath:indexPath)

Tells the delegate the table view is about to draw a cell for a particular row. 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.

Parameters:

  • tableView (UITableView) —

    The table-view object informing the delegate of this impending event.

  • cell (UITableViewCell) —

    A table-view cell object that tableView is going to use when drawing the row.

  • indexPath (NSIndexPath) —

    An index path locating the row in tableView.

Returns:

- (Object) tableView(tableView, willDisplayFooterView:view, forSection:section)

Tells the delegate that a footer view is about to be displayed for the specified section.

Parameters:

  • tableView (UITableView) —

    The table-view object informing the delegate of this event.

  • view (UIView) —

    The footer view that is about to be displayed.

  • section (Integer) —

    An index number identifying a section of tableView .

Returns:

- (Object) tableView(tableView, willDisplayHeaderView:view, forSection:section)

Tells the delegate that a header view is about to be displayed for the specified section.

Parameters:

  • tableView (UITableView) —

    The table-view object informing the delegate of this event.

  • view (UIView) —

    The header view that is about to be displayed.

  • section (Integer) —

    An index number identifying a section of tableView.

Returns:

- (NSIndexPath) tableView(tableView, willSelectRowAtIndexPath:indexPath)

Tells the delegate that a specified row is about to be 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 table view is in editing mode (that is, the editing property of the table view is set to YES) unless the table view allows selection during editing (that is, the allowsSelectionDuringEditing property of the table view is set to YES).

Parameters:

  • tableView (UITableView) —

    A table-view object informing the delegate about the impending selection.

  • indexPath (NSIndexPath) —

    An index path locating the row in tableView.

Returns:

  • (NSIndexPath) —

    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.