UITableViewDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
UITableView.h
Related sample code

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.

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.

Tasks

Configuring Rows for the Table View

Managing Accessory Views

Managing Selections

Modifying the Header and Footer of Sections

Editing Table Rows

Reordering Table Rows

Tracking the Removal of Views

Copying and Pasting Row Content

Managing Table View Highlighting

Instance Methods

tableView:accessoryButtonTappedForRowWithIndexPath:

Tells the delegate that the user tapped the accessory (disclosure) view associated with a given row.

- (void)tableView:(UITableView *)tableView accessoryButtonTappedForRowWithIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

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

indexPath

An index path locating the row in tableView.

Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:canPerformAction:forRowAtIndexPath:withSender:

Asks the delegate if the editing menu should omit the Copy or Paste command for a given row.

- (BOOL)tableView:(UITableView *)tableView canPerformAction:(SEL)action forRowAtIndexPath:(NSIndexPath *)indexPath withSender:(id)sender
Parameters
tableView

The table-view object that is making this request.

action

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

indexPath

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

sender

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

Return Value

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

Discussion

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
UITableView.h

tableView:didDeselectRowAtIndexPath:

Tells the delegate that the specified row is now deselected.

- (void)tableView:(UITableView *)tableView didDeselectRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

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

indexPath

An index path locating the deselected row in tableView.

Discussion

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

Availability
  • Available in iOS 3.0 and later.
Declared In
UITableView.h

tableView:didEndDisplayingCell:forRowAtIndexPath:

Tells the delegate that the specified cell was removed from the table.

- (void)tableView:(UITableView *)tableView didEndDisplayingCell:(UITableViewCell *)cell forRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object that removed the view.

cell

The cell that was removed.

indexPath

The index path of the cell.

Discussion

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.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITableView.h

tableView:didEndDisplayingFooterView:forSection:

Tells the delegate that the specified footer view was removed from the table.

- (void)tableView:(UITableView *)tableView didEndDisplayingFooterView:(UIView *)view forSection:(NSInteger)section
Parameters
tableView

The table-view object that removed the view.

view

The footer view that was removed.

section

The index of the section that contained the footer.

Discussion

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.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITableView.h

tableView:didEndDisplayingHeaderView:forSection:

Tells the delegate that the specified header view was removed from the table.

- (void)tableView:(UITableView *)tableView didEndDisplayingHeaderView:(UIView *)view forSection:(NSInteger)section
Parameters
tableView

The table-view object that removed the view.

view

The header view that was removed.

section

The index of the section that contained the header.

Discussion

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.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITableView.h

tableView:didEndEditingRowAtIndexPath:

Tells the delegate that the table view has left editing mode.

- (void)tableView:(UITableView *)tableView didEndEditingRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object providing this information.

indexPath

An index path locating the row in tableView.

Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:didHighlightRowAtIndexPath:

Tells the delegate that the specified row was highlighted.

- (void)tableView:(UITableView *)tableView didHighlightRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object that highlighted the cell.

indexPath

The index path of the row that was highlighted.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITableView.h

tableView:didSelectRowAtIndexPath:

Tells the delegate that the specified row is now selected.

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

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

indexPath

An index path locating the new selected row in tableView.

Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:didUnhighlightRowAtIndexPath:

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

- (void)tableView:(UITableView *)tableView didUnhighlightRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

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

indexPath

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

Availability
  • Available in iOS 6.0 and later.
Declared In
UITableView.h

tableView:editingStyleForRowAtIndexPath:

Asks the delegate for the editing style of a row at a particular location in a table view.

- (UITableViewCellEditingStyle)tableView:(UITableView *)tableView editingStyleForRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object requesting this information.

indexPath

An index path locating a row in tableView.

Return Value

The editing style of the cell for the row identified by indexPath.

Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:estimatedHeightForFooterInSection:

Asks the delegate for the estimated height of the footer of a particular section.

- (CGFloat)tableView:(UITableView *)tableView estimatedHeightForFooterInSection:(NSInteger)section
Parameters
tableView

The table-view object requesting this information.

section

An index number identifying a section of tableView .

Return Value

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

Discussion

Providing an estimate the height of section footers can improve the user experience when loading the table view. If the table contains variable height section footers, it might be expensive to calculate all their heights and so lead to a longer load time. Using estimation allows you to defer some of the cost of geometry calculation from load time to scrolling time.

Availability
  • Available in iOS 7.0 and later.
Declared In
UITableView.h

tableView:estimatedHeightForHeaderInSection:

Asks the delegate for the estimated height of the header of a particular section.

- (CGFloat)tableView:(UITableView *)tableView estimatedHeightForHeaderInSection:(NSInteger)section
Parameters
tableView

The table-view object requesting this information.

section

An index number identifying a section of tableView .

Return Value

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

Discussion

Providing an estimate the height of section headers can improve the user experience when loading the table view. If the table contains variable height section headers, it might be expensive to calculate all their heights and so lead to a longer load time. Using estimation allows you to defer some of the cost of geometry calculation from load time to scrolling time.

Availability
  • Available in iOS 7.0 and later.
Declared In
UITableView.h

tableView:estimatedHeightForRowAtIndexPath:

Asks the delegate for the estimated height of a row in a specified location.

- (CGFloat)tableView:(UITableView *)tableView estimatedHeightForRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object requesting this information.

indexPath

An index path that locates a row in tableView.

Return Value

A nonnegative floating-point value that estimates the height (in points) that row should be. Return UITableViewAutomaticDimension if you have no estimate.

Discussion

Providing an estimate the height of rows can improve the user experience when loading the table view. If the table contains variable height rows, it might be expensive to calculate all their heights and so lead to a longer load time. Using estimation allows you to defer some of the cost of geometry calculation from load time to scrolling time.

Availability
  • Available in iOS 7.0 and later.
Declared In
UITableView.h

tableView:heightForFooterInSection:

Asks the delegate for the height to use for the footer of a particular section.

- (CGFloat)tableView:(UITableView *)tableView heightForFooterInSection:(NSInteger)section
Parameters
tableView

The table-view object requesting this information.

section

An index number identifying a section of tableView .

Return Value

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

Discussion

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).

Special Considerations

Prior to iOS 5.0, table views would automatically resize the heights of footers to 0 for sections where tableView:viewForFooterInSection: returned a nil view. In iOS 5.0 and later, you must return the actual height for each section footer in this method.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:heightForHeaderInSection:

Asks the delegate for the height to use for the header of a particular section.

- (CGFloat)tableView:(UITableView *)tableView heightForHeaderInSection:(NSInteger)section
Parameters
tableView

The table-view object requesting this information.

section

An index number identifying a section of tableView .

Return Value

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

Discussion

This method allows the delegate to specify section headers with varying heights.

Special Considerations

Prior to iOS 5.0, table views would automatically resize the heights of headers to 0 for sections where tableView:viewForHeaderInSection: returned a nil view. In iOS 5.0 and later, you must return the actual height for each section header in this method.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:heightForRowAtIndexPath:

Asks the delegate for the height to use for a row in a specified location.

- (CGFloat)tableView:(UITableView *)tableView heightForRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object requesting this information.

indexPath

An index path that locates a row in tableView.

Return Value

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

Discussion

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). See also tableView:estimatedHeightForRowAtIndexPath:.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:indentationLevelForRowAtIndexPath:

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

- (NSInteger)tableView:(UITableView *)tableView indentationLevelForRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object requesting this information.

indexPath

An index path locating the row in tableView.

Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:performAction:forRowAtIndexPath:withSender:

Tells the delegate to perform a copy or paste operation on the content of a given row.

- (void)tableView:(UITableView *)tableView performAction:(SEL)action forRowAtIndexPath:(NSIndexPath *)indexPath withSender:(id)sender
Parameters
tableView

The table-view object that is making this request.

action

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

indexPath

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

sender

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

Discussion

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
UITableView.h

tableView:shouldHighlightRowAtIndexPath:

Asks the delegate if the specified row should be highlighted.

- (BOOL)tableView:(UITableView *)tableView shouldHighlightRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object that is making this request.

indexPath

The index path of the row being highlighted.

Return Value

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

Discussion

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.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITableView.h

tableView:shouldIndentWhileEditingRowAtIndexPath:

Asks 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
Parameters
tableView

The table-view object requesting this information.

indexPath

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

Return Value

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

Discussion

If the delegate does not implement this method, the default is YES. This method is unrelated to tableView:indentationLevelForRowAtIndexPath:.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:shouldShowMenuForRowAtIndexPath:

Asks the delegate if the editing menu should be shown for a certain row.

- (BOOL)tableView:(UITableView *)tableView shouldShowMenuForRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object that is making this request.

indexPath

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

Return Value

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

Discussion

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
UITableView.h

tableView:targetIndexPathForMoveFromRowAtIndexPath:toProposedIndexPath:

Asks 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
Parameters
tableView

The table-view object that is requesting this information.

sourceIndexPath

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

proposedDestinationIndexPath

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

Return Value

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

Discussion

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 another row, the destination row slides downward to visually make room for the relocation; this is the location identified by proposedDestinationIndexPath.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:titleForDeleteConfirmationButtonForRowAtIndexPath:

Changes the default title of the delete-confirmation button.

- (NSString *)tableView:(UITableView *)tableView titleForDeleteConfirmationButtonForRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object requesting this information.

indexPath

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

Return Value

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

Discussion

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.

Availability
  • Available in iOS 3.0 and later.
Declared In
UITableView.h

tableView:viewForFooterInSection:

Asks 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
Parameters
tableView

The table-view object asking for the view object.

section

An index number identifying a section of tableView .

Return Value

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

Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:viewForHeaderInSection:

Asks 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
Parameters
tableView

The table-view object asking for the view object.

section

An index number identifying a section of tableView .

Return Value

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

Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:willBeginEditingRowAtIndexPath:

Tells the delegate that the table view is about to go into editing mode.

- (void)tableView:(UITableView *)tableView willBeginEditingRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

The table-view object providing this information.

indexPath

An index path locating the row in tableView.

Discussion

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:.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

tableView:willDeselectRowAtIndexPath:

Tells the delegate that a specified row is about to be deselected.

- (NSIndexPath *)tableView:(UITableView *)tableView willDeselectRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

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

indexPath

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

Return Value

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.

Discussion

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.

Availability
  • Available in iOS 3.0 and later.
Declared In
UITableView.h

tableView:willDisplayCell:forRowAtIndexPath:

Tells 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
Parameters
tableView

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

cell

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

indexPath

An index path locating the row in tableView.

Discussion

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.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UITableView.h

tableView:willDisplayFooterView:forSection:

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

- (void)tableView:(UITableView *)tableView willDisplayFooterView:(UIView *)view forSection:(NSInteger)section
Parameters
tableView

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

view

The footer view that is about to be displayed.

section

An index number identifying a section of tableView .

Availability
  • Available in iOS 6.0 and later.
Declared In
UITableView.h

tableView:willDisplayHeaderView:forSection:

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

- (void)tableView:(UITableView *)tableView willDisplayHeaderView:(UIView *)view forSection:(NSInteger)section
Parameters
tableView

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

view

The header view that is about to be displayed.

section

An index number identifying a section of tableView.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITableView.h

tableView:willSelectRowAtIndexPath:

Tells the delegate that a specified row is about to be selected.

- (NSIndexPath *)tableView:(UITableView *)tableView willSelectRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
tableView

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

indexPath

An index path locating the row in tableView.

Return Value

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.

Discussion

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).

Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h