UITableView Overview

A table view displays a list of items in a single column.UITableViewis a subclass ofUIScrollView, which allows users to scroll through the table, althoughUITableViewallows vertical scrolling only. The cells comprising the individual items of the table areUITableViewCellobjects;UITableViewuses these objects to draw the visible rows of the table. Cells have content—titles and images—and can have, near the right edge, accessory views. Standard accessory views are disclosure indicators or detail disclosure buttons; the former leads to the next level in a data hierarchy and the latter leads to a detailed view of a selected item. Accessory views can also be framework controls, such as switches and sliders, or can be custom views. Table views can enter an editing mode where users can insert, delete, and reorder rows of the table.

A table view is made up of zero or more sections, each with its own rows. Sections are identified by their index number within the table view, and rows are identified by their index number within a section. Any section can optionally be preceded by a section header, and optionally be followed by a section footer.

Table views can have one of two styles,plainandgrouped. When you create aUITableViewinstance you must specify a table style, and this style cannot be changed. In the plain style, section headers and footers float above the content if the part of a complete section is visible. A table view can have an index that appears as a bar on the right hand side of the table (for example, "A" through "Z"). You can touch a particular label to jump to the target section. The grouped style of table view provides a default background color and a default background view for all cells. The background view provides a visual grouping for all cells in a particular section. For example, one group could be a person's name and title, another group for phone numbers that the person uses, and another group for email accounts and so on. See the Settings application for examples of grouped tables. Table views in the grouped style cannot have an index.

Many methods ofUITableViewtakeNSIndexPathobjects as parameters and return values.UITableViewdeclares a category onNSIndexPaththat enables you to get the represented row index (rowproperty) and section index (sectionproperty), and to construct an index path from a given row index and section index (init(row:section:)method). Especially in table views with multiple sections, you must evaluate the section index before identifying a row by its index number.

AUITableViewobject must have an object that acts as a data source and an object that acts as a delegate; typically these objects are either the application delegate or, more frequently, a customUITableViewControllerobject. The data source must adopt theUITableViewDataSourceprotocol and the delegate must adopt theUITableViewDelegateprotocol. The data source provides information thatUITableViewneeds to construct tables and manages the data model when rows of a table are inserted, deleted, or reordered. The delegate manages table row configuration and selection, row reordering, highlighting, accessory views, and editing operations.

When sent asetEditing(_:animated:)message (with a first parameter oftrue), the table view enters into editing mode where it shows the editing or reordering controls of each visible row, depending on theeditingStyleof each associatedUITableViewCell. Clicking on the insertion or deletion control causes the data source to receive atableView(_:commit:forRowAt:)message. You commit a deletion or insertion by callingdeleteRows(at:with:)orinsertRows(at:with:), as appropriate. Also in editing mode, if a table-view cell has itsshowsReorderControlproperty set totrue, the data source receives atableView(_:moveRowAt:to:)message. The data source can selectively remove the reordering control for cells by implementingtableView(_:canMoveRowAt:).

UITableViewcaches table-view cells for visible rows. You can create customUITableViewCellobjects with content or behavioral characteristics that are different than the default cells;A Closer Look at Table View Cellsexplains how.

UITableViewoverrides thelayoutSubviews()method ofUIViewso that it callsreloadData()only when you create a new instance ofUITableViewor when you assign a new data source. Reloading the table view clears current state, including the current selection. However, if you explicitly callreloadData(), it clears this state and any subsequent direct or indirect call tolayoutSubviews()does not trigger a reload.

For information about basic view behaviors, seeView Programming Guide for iOS.

State Preservation

In iOS 6 and later, if you assign a value to a table view’srestorationIdentifierproperty, it attempts to preserve the currently selected rows and the first visible row. The table’s data source may adopt theUIDataSourceModelAssociationprotocol, which provides a way to identify a row’s contents independent of that row’s position in the table. If the table’s data source adopts theUIDataSourceModelAssociationprotocol, the data source will be consulted when saving state to convert the index paths for the top visible row and any selected cells to identifiers. During restoration, the data source will be consulted to convert those identifiers back to index paths and reestablish the top visible row, and reselect the cells. If the table’s data source does not implement theUIDataSourceModelAssociationprotocol, the scroll position will be saved and restored directly, as will the index paths for selected cells.

For more information about how state preservation and restoration works, seeApp Programming Guide for iOS.

For more information about appearance and behavior configuration, seeTable Views.