UITableView Class Reference
| Inherits from | |
| 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
An instance of UITableView (or simply, a table view) is a means for displaying and editing hierarchical lists of information.
A table view in the UIKit framework is limited to a single column because it is designed for a device with a small screen. UITableView is a subclass of UIScrollView, which allows users to scroll through the table, although UITableView allows vertical scrolling only. The cells comprising the individual items of the table are UITableViewCell objects; UITableView uses 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, UITableViewStylePlain and UITableViewStyleGrouped. When you create a UITableView instance 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 of UITableView 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). Especially in table views with multiple sections, you must evaluate the section index before identifying a row by its index number.
A UITableView object 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 custom UITableViewController object. The data source must adopt the UITableViewDataSource protocol and the delegate must adopt the UITableViewDelegate protocol. The data source provides information that UITableView needs to construct tables and manages the data model when rows of a table are inserted, deleted, or reordered. The delegate provides the cells used by tables and performs other tasks, such as managing accessory views and selections.
When sent a setEditing:animated: message (with a first parameter of YES), the table view enters into editing mode where it shows the editing or reordering controls of each visible row, depending on the editingStyle of each associated UITableViewCell. Clicking on the insertion or deletion control causes the data source to receive a tableView:commitEditingStyle:forRowAtIndexPath: message. You commit a deletion or insertion by calling deleteRowsAtIndexPaths:withRowAnimation: or insertRowsAtIndexPaths:withRowAnimation:, as appropriate. Also in editing mode, if a table-view cell has its showsReorderControl property set to YES, the data source receives a tableView:moveRowAtIndexPath:toIndexPath: message. The data source can selectively remove the reordering control for cells by implementing tableView:canMoveRowAtIndexPath:.
UITableView caches table-view cells only for visible rows, but caches row, header, and footer heights for the entire table. You can create custom UITableViewCell objects with content or behavioral characteristics that are different than the default cells; "€œ“A Closer Look at Table-View Cells”" in Table View Programming Guide for iOS explains how.
UITableView overrides the layoutSubviews method of UIView so that it calls reloadData only when you create a new instance of UITableView or when you assign a new data source. Reloading the table view clears current state, including the current selection. However, if you explicitly call reloadData, it clears this state and any subsequent direct or indirect call to layoutSubviews does not trigger a reload.
Tasks
Initializing a UITableView Object
- – initWithFrame:style:
Configuring a Table View
- – dequeueReusableCellWithIdentifier:
- style property
- – numberOfRowsInSection:
- – numberOfSections
- rowHeight property
- separatorStyle property
- separatorColor property
- backgroundView property
- tableHeaderView property
- tableFooterView property
- sectionHeaderHeight property
- sectionFooterHeight property
- sectionIndexMinimumDisplayRowCount property
Accessing Cells and Sections
- – cellForRowAtIndexPath:
- – indexPathForCell:
- – indexPathForRowAtPoint:
- – indexPathsForRowsInRect:
- – visibleCells
- – indexPathsForVisibleRows
Scrolling the Table View
- – scrollToRowAtIndexPath:atScrollPosition:animated:
- – scrollToNearestSelectedRowAtScrollPosition:animated:
Managing Selections
- – indexPathForSelectedRow
- – indexPathsForSelectedRows
- – selectRowAtIndexPath:animated:scrollPosition:
- – deselectRowAtIndexPath:animated:
- allowsSelection property
- allowsMultipleSelection property
- allowsSelectionDuringEditing property
- allowsMultipleSelectionDuringEditing property
Inserting, Deleting, and Moving Rows and Sections
- – beginUpdates
- – endUpdates
- – insertRowsAtIndexPaths:withRowAnimation:
- – deleteRowsAtIndexPaths:withRowAnimation:
- – moveRowAtIndexPath:toIndexPath:
- – insertSections:withRowAnimation:
- – deleteSections:withRowAnimation:
- – moveSection:toSection:
Managing the Editing of Table Cells
- editing property
- – setEditing:animated:
Reloading the Table View
- – reloadData
- – reloadRowsAtIndexPaths:withRowAnimation:
- – reloadSections:withRowAnimation:
- – reloadSectionIndexTitles
Accessing Drawing Areas of the Table View
- – rectForSection:
- – rectForRowAtIndexPath:
- – rectForFooterInSection:
- – rectForHeaderInSection:
Registering Nib Objects for Cell Reuse
- – registerNib:forCellReuseIdentifier:
Managing the Delegate and the Data Source
- dataSource property
- delegate property
Properties
allowsMultipleSelection
A Boolean value that determines whether users can select more than one row outside of editing mode.
@property(nonatomic) BOOL allowsMultipleSelection
Discussion
This property controls whether multiple rows can be selected simultaneously outside of editing mode. When the value of this property is YES, a check mark is placed next to each row that is tapped. Tapping the row again removes the check mark. If you call indexPathsForSelectedRows, you can get the index paths that identify the selected rows.
The default value of this property is NO.
Availability
- Available in iOS 5.0 and later.
See Also
- @property allowsSelection
- @property allowsSelectionDuringEditing
- @property allowsMultipleSelectionDuringEditing
Declared In
UITableView.h
allowsMultipleSelectionDuringEditing
A Boolean value that controls whether users can select more than one cell simultaneously in editing mode.
@property(nonatomic) BOOL allowsMultipleSelectionDuringEditing
Discussion
The default value of this property is NO. If you it to YES, check marks appear next to selected rows in editing mode. In addition, UITableView does not query for editing styles when it goes into editing mode. If you call indexPathsForSelectedRows, you can get the index paths that identify the selected rows.
Availability
- Available in iOS 5.0 and later.
See Also
- @property allowsSelection
- @property allowsMultipleSelection
- @property allowsSelectionDuringEditing
Declared In
UITableView.h
allowsSelection
A Boolean value that determines whether users can select a row.
@property(nonatomic) BOOL allowsSelection
Discussion
If the value of this property is YES (the default), users can select rows. If you set it to NO, they cannot select rows. Setting this property affects cell selection only when the table view is not in editing mode. If you want to restrict selection of cells in editing mode, use allowsSelectionDuringEditing.
Availability
- Available in iOS 3.0 and later.
See Also
- @property allowsMultipleSelection
- @property allowsSelectionDuringEditing
Related Sample Code
Declared In
UITableView.h
allowsSelectionDuringEditing
A Boolean value that determines whether users can select cells while the receiver is in editing mode.
@property(nonatomic) BOOL allowsSelectionDuringEditing
Discussion
If the value of this property is YES , users can select rows during editing. The default value is NO. If you want to restrict selection of cells regardless of mode, use allowsSelection.
Availability
- Available in iOS 2.0 and later.
See Also
- @property allowsSelection
- @property allowsMultipleSelection
- @property allowsMultipleSelectionDuringEditing
Declared In
UITableView.h
backgroundView
The background view of the table view.
@property(nonatomic, readwrite, retain) UIView *backgroundView
Discussion
A table view’s background view is automatically resized to match the size of the table view. This view is placed as a subview of the table view behind all cells , header views, and footer views.
Availability
- Available in iOS 3.2 and later.
Declared In
UITableView.h
dataSource
The object that acts as the data source of the receiving table view.
@property(nonatomic, assign) id<UITableViewDataSource> dataSource
Discussion
The data source must adopt the UITableViewDataSource protocol. The data source is not retained.
Availability
- Available in iOS 2.0 and later.
See Also
- @property delegate
Related Sample Code
Declared In
UITableView.h
delegate
The object that acts as the delegate of the receiving table view.
@property(nonatomic, assign) id<UITableViewDelegate> delegate
Discussion
The delegate must adopt the UITableViewDelegate protocol. The delegate is not retained.
Availability
- Available in iOS 2.0 and later.
See Also
- @property dataSource
Related Sample Code
Declared In
UITableView.h
editing
A Boolean value that determines whether the receiver is in editing mode.
@property(nonatomic, getter=isEditing) BOOL editing
Discussion
When the value of this property is YES , the table view is in editing mode: the cells of the table might show an insertion or deletion control on the left side of each cell and a reordering control on the right side, depending on how the cell is configured. (SeeUITableViewCell Class Reference for details.) Tapping a control causes the table view to invoke the data source method tableView:commitEditingStyle:forRowAtIndexPath:. The default value is NO.
Availability
- Available in iOS 2.0 and later.
See Also
- – setEditing:animated:
Related Sample Code
Declared In
UITableView.h
rowHeight
The height of each row (table cell) in the receiver.
@property(nonatomic) CGFloat rowHeight
Discussion
The row height is in points. You may set the row height for cells if the delegate doesn't implement the tableView:heightForRowAtIndexPath: method. If you do not explicitly set the row height, UITableView sets it to a standard value.
There are performance implications to using tableView:heightForRowAtIndexPath: instead of rowHeight. 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).
Availability
- Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITableView.h
sectionFooterHeight
The height of section footers in the receiving table view.
@property(nonatomic) CGFloat sectionFooterHeight
Discussion
This value is used only in section group tables, and only if the delegate doesn't implement the tableView:heightForFooterInSection: method.
Availability
- Available in iOS 2.0 and later.
See Also
- @property tableFooterView
Declared In
UITableView.h
sectionHeaderHeight
The height of section headers in the receiving table view.
@property(nonatomic) CGFloat sectionHeaderHeight
Discussion
This value is used only if delegate the doesn't implement the tableView:heightForHeaderInSection: method.
Availability
- Available in iOS 2.0 and later.
See Also
- @property tableHeaderView
Declared In
UITableView.h
sectionIndexMinimumDisplayRowCount
The number of table rows at which to display the index list on the right edge of the table.
@property(nonatomic) NSInteger sectionIndexMinimumDisplayRowCount
Discussion
This property is applicable only to table views in the UITableViewStylePlain style. The default value is NSIntegerMax.
Availability
- Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITableView.h
separatorColor
The color of separator rows in the table view.
@property(nonatomic, retain) UIColor *separatorColor
Discussion
The default color is gray.
Availability
- Available in iOS 2.0 and later.
See Also
- @property separatorStyle
Declared In
UITableView.h
separatorStyle
The style for table cells used as separators.
@property(nonatomic) UITableViewCellSeparatorStyle separatorStyle
Discussion
The value of this property is one of the separator-style constants described in UITableViewCell Class Reference class reference. UITableView uses this property to set the separator style on the cell returned from the delegate in tableView:cellForRowAtIndexPath:.
Availability
- Available in iOS 2.0 and later.
See Also
- @property separatorColor
Related Sample Code
Declared In
UITableView.h
style
Returns the style of the receiver. (read-only)
@property(nonatomic, readonly) UITableViewStyle style
Discussion
See “Table View Style” for descriptions of the constants used to specify table-view style.
Availability
- Available in iOS 2.0 and later.
Declared In
UITableView.h
tableFooterView
Returns an accessory view that is displayed below the table.
@property(nonatomic, retain) UIView *tableFooterView
Discussion
The default value is nil. The table footer view is different from a section footer.
Availability
- Available in iOS 2.0 and later.
See Also
- @property sectionFooterHeight
Declared In
UITableView.h
tableHeaderView
Returns an accessory view that is displayed above the table.
@property(nonatomic, retain) UIView *tableHeaderView
Discussion
The default value is nil. The table header view is different from a section header.
Availability
- Available in iOS 2.0 and later.
See Also
- @property sectionHeaderHeight
Declared In
UITableView.h
Instance Methods
beginUpdates
Begin a series of method calls that insert, delete, or select rows and sections of the receiver.
- (void)beginUpdates
Discussion
Call this method if you want subsequent insertions, deletion, and selection operations (for example, cellForRowAtIndexPath: and indexPathsForVisibleRows) to be animated simultaneously. This group of methods must conclude with an invocation of endUpdates. These method pairs can be nested. If you do not make the insertion, deletion, and selection calls inside this block, table attributes such as row count might become invalid. You should not call reloadData within the group; if you call this method within the group, you will need to perform any animations yourself.
Availability
- Available in iOS 2.0 and later.
Declared In
UITableView.h
cellForRowAtIndexPath:
Returns the table cell at the specified index path.
- (UITableViewCell *)cellForRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
indexPath
The index path locating the row in the receiver.
Return Value
An object representing a cell of the table or nil if the cell is not visible or indexPath is out of range.
Availability
- Available in iOS 2.0 and later.
See Also
- – indexPathForCell:
Related Sample Code
Declared In
UITableView.h
deleteRowsAtIndexPaths:withRowAnimation:
Deletes the rows specified by an array of index paths, with an option to animate the deletion.
- (void)deleteRowsAtIndexPaths:(NSArray *)indexPaths withRowAnimation:(UITableViewRowAnimation)animation
Parameters
indexPaths
An array of NSIndexPath objects identifying the rows to delete.
animation
A constant that indicates how the deletion is to be animated, for example, fade out or slide out from the bottom. See “Table Cell Insertion and Deletion Animation” for descriptions of these constants.
Discussion
Note the behavior of this method when it is called in an animation block defined by the beginUpdates and endUpdates methods. UITableView defers any insertions of rows or sections until after it has handled the deletions of rows or sections. This happens regardless of ordering of the insertion and deletion method calls. This is unlike inserting or removing an item in a mutable array, where the operation can affect the array index used for the successive insertion or removal operation. For more on this subject, see “Batch Insertion and Deletion of Rows and Sections” in Table View Programming Guide for iOS.
Availability
- Available in iOS 2.0 and later.
See Also
- – insertRowsAtIndexPaths:withRowAnimation:
- – moveRowAtIndexPath:toIndexPath:
- – reloadRowsAtIndexPaths:withRowAnimation:
Related Sample Code
Declared In
UITableView.h
deleteSections:withRowAnimation:
Deletes one or more sections in the receiver, with an option to animate the deletion.
- (void)deleteSections:(NSIndexSet *)sections withRowAnimation:(UITableViewRowAnimation)animation
Parameters
sections
An index set that specifies the sections to delete from the receiving table view. If a section exists after the specified index location, it is moved up one index location.
animation
A constant that either specifies the kind of animation to perform when deleting the section or requests no animation. See “Table Cell Insertion and Deletion Animation” for descriptions of the constants.
Discussion
Note the behavior of this method when it is called in an animation block defined by the beginUpdates and endUpdates methods. UITableView defers any insertions of rows or sections until after it has handled the deletions of rows or sections. This happens regardless of ordering of the insertion and deletion method calls. This is unlike inserting or removing an item in a mutable array, where the operation can affect the array index used for the successive insertion or removal operation. For more on this subject, see “Batch Insertion and Deletion of Rows and Sections” in Table View Programming Guide for iOS.
Availability
- Available in iOS 2.0 and later.
See Also
- – insertSections:withRowAnimation:
- – moveSection:toSection:
- – reloadSections:withRowAnimation:
Related Sample Code
Declared In
UITableView.h
dequeueReusableCellWithIdentifier:
Returns a reusable table-view cell object located by its identifier.
- (id)dequeueReusableCellWithIdentifier:(NSString *)identifier
Parameters
identifier
A string identifying the cell object to be reused. By default, a reusable cell’€™s identifier is its class name, but you can change it to any arbitrary value.
Return Value
A UITableViewCell object with the associated identifier or nil if no such object exists in the reusable-cell queue.
Discussion
For performance reasons, a table view'€™s data source should generally reuse UITableViewCell objects when it assigns cells to rows in its tableView:cellForRowAtIndexPath: method. A table view maintains a queue or list of UITableViewCell objects that the table view's delegate has marked for reuse. It marks a cell for reuse by assigning it a reuse identifier when it creates it (that is, in the initWithFrame:reuseIdentifier: method of UITableViewCell). The data source can access specific template cell objects in this queue by invoking the dequeueReusableCellWithIdentifier: method. You can access a cell'€™s reuse identifier through its reuseIdentifier property, which is defined by UITableViewCell.
Availability
- Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITableView.h
deselectRowAtIndexPath:animated:
Deselects a given row identified by index path, with an option to animate the deselection.
- (void)deselectRowAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animated
Parameters
indexPath
An index path identifying a row in the receiver.
animated
YES if you want to animate the deselection and NO if the change should be immediate.
Discussion
Calling this method does not cause the delegate to receive a tableView:willSelectRowAtIndexPath: or tableView:didSelectRowAtIndexPath: message, nor will it send UITableViewSelectionDidChangeNotification notifications to observers.
Calling this method does not cause any scrolling to the deselected row.
Availability
- Available in iOS 2.0 and later.
See Also
- – indexPathForSelectedRow
Related Sample Code
Declared In
UITableView.h
endUpdates
Conclude a series of method calls that insert, delete, select, or reload rows and sections of the receiver.
- (void)endUpdates
Discussion
You call this method to bracket a series of method calls that began with beginUpdates and that consist of operations to insert, delete, select, and reload rows and sections of the table view. When you call endUpdates, UITableView animates the operations simultaneously. Invocations of beginUpdates and endUpdates can be nested. If you do not make the insertion, deletion, and selection calls inside this block, table attributes such as row count might become invalid.
Availability
- Available in iOS 2.0 and later.
Declared In
UITableView.h
indexPathForCell:
Returns an index path representing the row and section of a given table-view cell.
- (NSIndexPath *)indexPathForCell:(UITableViewCell *)cell
Parameters
cell
A cell object of the table view.
Return Value
An index path representing the row and section of the cell or nil if the index path is invalid.
Availability
- Available in iOS 2.0 and later.
See Also
- – cellForRowAtIndexPath:
Declared In
UITableView.h
indexPathForRowAtPoint:
Returns an index path identifying the row and section at the given point.
- (NSIndexPath *)indexPathForRowAtPoint:(CGPoint)point
Parameters
point
A point in the local coordinate system of the receiver (the table view'€™s bounds).
Return Value
An index path representing the row and section associated with point or nil if the point is out of the bounds of any row.
Availability
- Available in iOS 2.0 and later.
See Also
- – indexPathForCell:
Declared In
UITableView.h
indexPathForSelectedRow
Returns an index path identifying the row and section of the selected row.
- (NSIndexPath *)indexPathForSelectedRow
Return Value
An index path identifying the row and section indexes of the selected row or nil if the index path is invalid.
Discussion
If there are multiple selections, this method returns the first index-path object in the array of row selections; this object has the lowest index values for section and row.
Availability
- Available in iOS 2.0 and later.
See Also
- – selectRowAtIndexPath:animated:scrollPosition:
- – indexPathsForSelectedRows
Declared In
UITableView.h
indexPathsForRowsInRect:
An array of index paths each representing a row enclosed by a given rectangle.
- (NSArray *)indexPathsForRowsInRect:(CGRect)rect
Parameters
rect
A rectangle defining an area of the table view in local coordinates.
Return Value
An array of NSIndexPath objects each representing a row and section index identifying a row within rect. Returns an empty array if there aren’t any rows to return.
Availability
- Available in iOS 2.0 and later.
See Also
- – indexPathForRowAtPoint:
Declared In
UITableView.h
indexPathsForSelectedRows
Returns the index paths represented the selected rows.
- (NSArray *)indexPathsForSelectedRows
Return Value
An array of index-path objects each identifying a row through its section and row index. Returns nil if there are no selected rows.
Availability
- Available in iOS 5.0 and later.
See Also
- – indexPathForSelectedRow
Declared In
UITableView.h
indexPathsForVisibleRows
Returns an array of index paths each identifying a visible row in the receiver.
- (NSArray *)indexPathsForVisibleRows
Return Value
An array of NSIndexPath objects each representing a row index and section index that together identify a visible row in the table view. Returns nil if no rows are visible.
Availability
- Available in iOS 2.0 and later.
See Also
- – visibleCells
Declared In
UITableView.h
initWithFrame:style:
Initializes and returns a table view object having the given frame and style.
- (id)initWithFrame:(CGRect)frame style:(UITableViewStyle)style
Parameters
frame
A rectangle specifying the initial location and size of the table view in its superview'€™s coordinates. The frame of the table view changes as table cells are added and deleted.
style
A constant that specifies the style of the table view. See “Table View Style” for descriptions of valid constants.
Return Value
Returns an initialized UITableView object or nil if the object could not be successfully initialized.
Discussion
You must specify the style of a table view when you create it and you cannot thereafter modify the style. If you initialize the table view with the UIView method initWithFrame:, the UITableViewStylePlain style is used as a default.
Availability
- Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITableView.h
insertRowsAtIndexPaths:withRowAnimation:
Inserts rows in the receiver at the locations identified by an array of index paths, with an option to animate the insertion.
- (void)insertRowsAtIndexPaths:(NSArray *)indexPaths withRowAnimation:(UITableViewRowAnimation)animation
Parameters
indexPaths
An array of NSIndexPath objects each representing a row index and section index that together identify a row in the table view.
animation
A constant that either specifies the kind of animation to perform when inserting the cell or requests no animation. See “Table Cell Insertion and Deletion Animation” for descriptions of the constants.
Discussion
UITableView calls the relevant delegate and data source methods immediately afterwards to get the cells and other content for visible cells.
Note the behavior of this method when it is called in an animation block defined by the beginUpdates and endUpdates methods. UITableView defers any insertions of rows or sections until after it has handled the deletions of rows or sections. This happens regardless of ordering of the insertion and deletion method calls. This is unlike inserting or removing an item in a mutable array, where the operation can affect the array index used for the successive insertion or removal operation. For more on this subject, see “Batch Insertion and Deletion of Rows and Sections” in Table View Programming Guide for iOS.
Availability
- Available in iOS 2.0 and later.
See Also
- – insertSections:withRowAnimation:
- – deleteRowsAtIndexPaths:withRowAnimation:
- – moveRowAtIndexPath:toIndexPath:
- – reloadRowsAtIndexPaths:withRowAnimation:
Related Sample Code
Declared In
UITableView.h
insertSections:withRowAnimation:
Inserts one or more sections in the receiver, with an option to animate the insertion.
- (void)insertSections:(NSIndexSet *)sections withRowAnimation:(UITableViewRowAnimation)animation
Parameters
sections
An index set that specifies the sections to insert in the receiving table view. If a section already exists at the specified index location, it is moved down one index location.
animation
A constant that indicates how the insertion is to be animated, for example, fade in or slide in from the left. See “Table Cell Insertion and Deletion Animation” for descriptions of these constants.
Discussion
UITableView calls the relevant delegate and data source methods immediately afterwards to get the cells and other content for visible cells.
Note the behavior of this method when it is called in an animation block defined by the beginUpdates and endUpdates methods. UITableView defers any insertions of rows or sections until after it has handled the deletions of rows or sections. This happens regardless of ordering of the insertion and deletion method calls. This is unlike inserting or removing an item in a mutable array, where the operation can affect the array index used for the successive insertion or removal operation. For more on this subject, see “Batch Insertion and Deletion of Rows and Sections” in Table View Programming Guide for iOS.
Availability
- Available in iOS 2.0 and later.
See Also
- – insertRowsAtIndexPaths:withRowAnimation:
- – deleteSections:withRowAnimation:
- – moveSection:toSection:
- – reloadSections:withRowAnimation:
Related Sample Code
Declared In
UITableView.h
moveRowAtIndexPath:toIndexPath:
Moves the row at a specified location to a destination location.
- (void)moveRowAtIndexPath:(NSIndexPath *)indexPath toIndexPath:(NSIndexPath *)newIndexPath
Parameters
indexPath
An index path identifying the row to move.
newIndexPath
An index path identifying the row that is the destination of the row at indexPath. The existing row at that location slides up or down to an adjoining index position to make room for it.
Discussion
You can combine row-move operations with row-insertion and row-deletion operations within a beginUpdates–endUpdates block to have all changes occur together as a single animation.
Unlike the row-insertion and row-deletion methods, this method does not take an animation parameter. For rows that are moved, the moved row animates straight from the starting position to the ending postion. Also unlike the other methods, this method allows only one row to be moved per call. If you want multiple rows moved, you can call this method repeatedly within a beginUpdates–endUpdates block.
Availability
- Available in iOS 5.0 and later.
See Also
- – insertRowsAtIndexPaths:withRowAnimation:
- – deleteRowsAtIndexPaths:withRowAnimation:
- – reloadRowsAtIndexPaths:withRowAnimation:
Declared In
UITableView.h
moveSection:toSection:
Moves a section to a new location in the table view.
- (void)moveSection:(NSInteger)section toSection:(NSInteger)newSection
Parameters
section
The index of the section to move.
newSection
The index in the table view that is the destination of the move for the section. The existing section at that location slides up or down to an adjoining index position to make room for it.
Discussion
You can combine section-move operations with section-insertion and section-deletion operations within a beginUpdates–endUpdates block to have all changes occur together as a single animation.
Unlike the section-insertion section row-deletion methods, this method does not take an animation parameter. For sections that are moved, the moved section animates straight from the starting position to the ending postion. Also unlike the other methods, this method allows only one section to be moved per call. If you want multiple section moved, you can call this method repeatedly within a beginUpdates–endUpdates block.
Availability
- Available in iOS 5.0 and later.
See Also
- – insertSections:withRowAnimation:
- – deleteSections:withRowAnimation:
Declared In
UITableView.h
numberOfRowsInSection:
Returns the number of rows (table cells) in a specified section.
- (NSInteger)numberOfRowsInSection:(NSInteger)section
Parameters
section
An index number that identifies a section of the table. Table views in a plain style have a section index of zero.
Return Value
The number of rows in the section.
Discussion
UITableView gets the value returned by this method from its data source and caches it.
Availability
- Available in iOS 2.0 and later.
See Also
- – numberOfSections
Declared In
UITableView.h
numberOfSections
Returns the number of sections for the receiver.
- (NSInteger)numberOfSections
Return Value
The number of sections in the table view.
Discussion
UITableView gets the value returned by this method from its data source and caches it.
Availability
- Available in iOS 2.0 and later.
See Also
- – numberOfRowsInSection:
Declared In
UITableView.h
rectForFooterInSection:
Returns the drawing area for the footer of the specified section.
- (CGRect)rectForFooterInSection:(NSInteger)section
Parameters
section
An index number identifying a section of the table view. Plain-style table views always have a section index of zero.
Return Value
A rectangle defining the area in which the table view draws the section footer.
Availability
- Available in iOS 2.0 and later.
Declared In
UITableView.h
rectForHeaderInSection:
Returns the drawing area for the header of the specified section.
- (CGRect)rectForHeaderInSection:(NSInteger)section
Parameters
section
An index number identifying a section of the table view. Plain-style table views always have a section index of zero.
Return Value
A rectangle defining the area in which the table view draws the section header.
Availability
- Available in iOS 2.0 and later.
Declared In
UITableView.h
rectForRowAtIndexPath:
Returns the drawing area for a row identified by index path.
- (CGRect)rectForRowAtIndexPath:(NSIndexPath *)indexPath
Parameters
indexPath
An index path object that identifies a row by its index and its section index.
Return Value
A rectangle defining the area in which the table view draws the row or CGRectZero if indexPath is invalid.
Availability
- Available in iOS 2.0 and later.
Declared In
UITableView.h
rectForSection:
Returns the drawing area for a specified section of the receiver.
- (CGRect)rectForSection:(NSInteger)section
Parameters
section
An index number identifying a section of the table view. Plain-style table views always have a section index of zero.
Return Value
A rectangle defining the area in which the table view draws the section.
Availability
- Available in iOS 2.0 and later.
Declared In
UITableView.h
registerNib:forCellReuseIdentifier:
Registers a nib object containing a cell with the table view under a specified identifier.
- (void)registerNib:(UINib *)nib forCellReuseIdentifier:(NSString *)identifier
Parameters
nib
A nib object created from a nib file. This parameter cannot be nil.
identifier
An arbitrary string identifier to use for the cell. This parameter cannot be nil.
Discussion
When you register a nib object with the table view and later call the dequeueReusableCellWithIdentifier: method, passing in the registered identifier, the table view instantiates the cell from the nib object if it is not already in the reuse queue.
Availability
- Available in iOS 5.0 and later.
See Also
- tableView:cellForRowAtIndexPath: (UITableViewDataSource)
Declared In
UITableView.h
reloadData
Reloads the rows and sections of the receiver.
- (void)reloadData
Discussion
Call this method to reload all the data that is used to construct the table, including cells, section headers and footers, index arrays, and so on. For efficiency, the table view redisplays only those rows that are visible. It adjusts offsets if the table shrinks as a result of the reload. The table view'€™s delegate or data source calls this method when it wants the table view to completely reload its data. It should not be called in the methods that insert or delete rows, especially within an animation block implemented with calls to beginUpdates and endUpdates
Availability
- Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITableView.h
reloadRowsAtIndexPaths:withRowAnimation:
Reloads the specified rows using a certain animation effect.
- (void)reloadRowsAtIndexPaths:(NSArray *)indexPaths withRowAnimation:(UITableViewRowAnimation)animation
Parameters
indexPaths
An array of NSIndexPath objects identifying the rows to reload.
animation
A constant that indicates how the reloading is to be animated, for example, fade out or slide out from the bottom. See “Table Cell Insertion and Deletion Animation” for descriptions of these constants.
The animation constant affects the direction in which both the old and the new rows slide. For example, if the animation constant is UITableViewRowAnimationRight, the old rows slide out to the right and the new cells slide in from the right.
Discussion
Reloading a row causes the table view to ask its data source for a new cell for that row. The table animates that new cell in as it animates the old row out. Call this method if you want to alert the user that the value of a cell is changing. If, however, notifying the user is not important—that is, you just want to change the value that a cell is displaying—you can get the cell for a particular row and set its new value.
When this method is called in an animation block defined by the beginUpdates and endUpdates methods, it behaves similarly to deleteRowsAtIndexPaths:withRowAnimation:. The indexes that UITableView passes to the method are specified in the state of the table view prior to any updates. This happens regardless of ordering of the insertion, deletion, and reloading method calls within the animation block.
Availability
- Available in iOS 3.0 and later.
See Also
- – insertRowsAtIndexPaths:withRowAnimation:
Related Sample Code
Declared In
UITableView.h
reloadSectionIndexTitles
Reloads the items in the index bar along the right side of the table view.
- (void)reloadSectionIndexTitles
Discussion
This method gives you a way to update the section index after inserting or deleting sections without having to reload the whole table.
Availability
- Available in iOS 3.0 and later.
See Also
- sectionIndexTitlesForTableView: (UITableViewDataSource)
Declared In
UITableView.h
reloadSections:withRowAnimation:
Reloads the specified sections using a given animation effect.
- (void)reloadSections:(NSIndexSet *)sections withRowAnimation:(UITableViewRowAnimation)animation
Parameters
sections
An index set identifying the sections to reload.
animation
A constant that indicates how the reloading is to be animated, for example, fade out or slide out from the bottom. See “Table Cell Insertion and Deletion Animation” for descriptions of these constants.
The animation constant affects the direction in which both the old and the new section rows slide. For example, if the animation constant is UITableViewRowAnimationRight, the old rows slide out to the right and the new cells slide in from the right.
Discussion
Calling this method causes the table view to ask its data source for new cells for the specified sections. The table view animates the insertion of new cells in as it animates the old cells out. Call this method if you want to alert the user that the values of the designated sections are changing. If, however, you just want to change values in cells of the specified sections without alerting the user, you can get those cells and directly set their new values.
When this method is called in an animation block defined by the beginUpdates and endUpdates methods, it behaves similarly to deleteSections:withRowAnimation:. The indexes that UITableView passes to the method are specified in the state of the table view prior to any updates. This happens regardless of ordering of the insertion, deletion, and reloading method calls within the animation block.
Availability
- Available in iOS 3.0 and later.
See Also
- – insertSections:withRowAnimation:
Declared In
UITableView.h
scrollToNearestSelectedRowAtScrollPosition:animated:
Scrolls the table view so that the selected row nearest to a specified position in the table view is at that position.
- (void)scrollToNearestSelectedRowAtScrollPosition:(UITableViewScrollPosition)scrollPosition animated:(BOOL)animated
Parameters
scrollPosition
A constant that identifies a relative position in the receiving table view (top, middle, bottom) for the row when scrolling concludes. See “Table View Scroll Position” a descriptions of valid constants.
animated
YES if you want to animate the change in position, NO if it should be immediate.
Availability
- Available in iOS 2.0 and later.
See Also
- – scrollToRowAtIndexPath:atScrollPosition:animated:
Declared In
UITableView.h
scrollToRowAtIndexPath:atScrollPosition:animated:
Scrolls the receiver until a row identified by index path is at a particular location on the screen.
- (void)scrollToRowAtIndexPath:(NSIndexPath *)indexPath atScrollPosition:(UITableViewScrollPosition)scrollPosition animated:(BOOL)animated
Parameters
indexPath
An index path that identifies a row in the table view by its row index and its section index.
scrollPosition
A constant that identifies a relative position in the receiving table view (top, middle, bottom) for row when scrolling concludes. See “Table View Scroll Position” a descriptions of valid constants.
animated
YES if you want to animate the change in position, NO if it should be immediate.
Discussion
Invoking this method does not cause the delegate to receive a scrollViewDidScroll: message, as is normal for programmatically-invoked user interface operations.
Availability
- Available in iOS 2.0 and later.
See Also
- – scrollToNearestSelectedRowAtScrollPosition:animated:
Declared In
UITableView.h
selectRowAtIndexPath:animated:scrollPosition:
Selects a row in the receiver identified by index path, optionally scrolling the row to a location in the receiver.
- (void)selectRowAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animated scrollPosition:(UITableViewScrollPosition)scrollPosition
Parameters
indexPath
An index path identifying a row in the receiver.
animated
YES if you want to animate the selection and any change in position, NO if the change should be immediate.
scrollPosition
A constant that identifies a relative position in the receiving table view (top, middle, bottom) for the row when scrolling concludes. See “Table View Scroll Position” a descriptions of valid constants.
Discussion
Calling this method does not cause the delegate to receive a tableView:willSelectRowAtIndexPath: or tableView:didSelectRowAtIndexPath: message, nor will it send UITableViewSelectionDidChangeNotification notifications to observers.
Special Considerations
Passing UITableViewScrollPositionNone will result in no scrolling, rather than the minimum scrolling described for that constant. To scroll to the newly selected row with minimum scrolling, select the row using this method with UITableViewScrollPositionNone, then call scrollToRowAtIndexPath:atScrollPosition:animated: with UITableViewScrollPositionNone.
| NSIndexPath *rowToSelect; // assume this exists and is set properly
|
| UITableView *myTableView; // assume this exists
|
|
|
| [myTableView selectRowAtIndexPath:rowToSelect animated:YES scrollPosition:UITableViewScrollPositionNone;
|
| [myTableView scrollToRowAtIndexPath:rowToSelect atScrollPosition:UITableViewScrollPositionNon animate:YES];
|
Availability
- Available in iOS 2.0 and later.
See Also
- – indexPathForSelectedRow
Declared In
UITableView.h
setEditing:animated:
Toggles the receiver into and out of editing mode.
- (void)setEditing:(BOOL)editing animated:(BOOL)animate
Parameters
editing
YES to enter editing mode, NO to leave it. The default value is NO .
animate
YES to animate the transition to editing mode, NO to make the transition immediate.
Discussion
When you call this method with the value of editing set to YES, the table view goes into editing mode by calling setEditing:animated: on each visible UITableViewCell object. Calling this method with editing set to NO turns off editing mode. In editing mode, the cells of the table might show an insertion or deletion control on the left side of each cell and a reordering control on the right side, depending on how the cell is configured. (See UITableViewCell Class Reference for details.) The data source of the table view can selectively exclude cells from editing mode by implementing tableView:canEditRowAtIndexPath:.
Availability
- Available in iOS 2.0 and later.
See Also
- @property editing
Declared In
UITableView.h
visibleCells
Returns the table cells that are visible in the receiver.
- (NSArray *)visibleCells
Return Value
An array containing UITableViewCell objects, each representing a visible cell in the receiving table view.
Availability
- Available in iOS 2.0 and later.
See Also
- – indexPathsForVisibleRows
Related Sample Code
Declared In
UITableView.h
Constants
Table View Style
The style of the table view.
typedef enum {
UITableViewStylePlain,
UITableViewStyleGrouped
} UITableViewStyle;
Constants
UITableViewStylePlain
A plain table view. Any section headers or footers are displayed as inline separators and float when the table view is scrolled.
Available in iOS 2.0 and later.
Declared in UITableView.h.
UITableViewStyleGrouped
A table view whose sections present distinct groups of rows. The section headers and footers do not float.
Available in iOS 2.0 and later.
Declared in UITableView.h.
Discussion
You set the table style when you initialize the table view (see initWithFrame:style:). You cannot modify the style thereafter.
Declared In
UITableView.h
Table View Scroll Position
The position in the table view (top, middle, bottom) to which a given row is scrolled.
typedef enum {
UITableViewScrollPositionNone,
UITableViewScrollPositionTop,
UITableViewScrollPositionMiddle,
UITableViewScrollPositionBottom
} UITableViewScrollPosition;
Constants
UITableViewScrollPositionNone
The table view scrolls the row of interest to be fully visible with a minimum of movement. If the row is already fully visible, no scrolling occurs. For example, if the row is above the visible area, the behavior is identical to that specified by UITableViewScrollPositionTop. This is the default.
Available in iOS 2.0 and later.
Declared in UITableView.h.
UITableViewScrollPositionTop
The table view scrolls the row of interest to the top of the visible table view.
Available in iOS 2.0 and later.
Declared in UITableView.h.
UITableViewScrollPositionMiddle
The table view scrolls the row of interest to the middle of the visible table view.
Available in iOS 2.0 and later.
Declared in UITableView.h.
UITableViewScrollPositionBottom
The table view scrolls the row of interest to the bottom of the visible table view.
Available in iOS 2.0 and later.
Declared in UITableView.h.
Discussion
You set the scroll position through a parameter of the selectRowAtIndexPath:animated:scrollPosition:, scrollToNearestSelectedRowAtScrollPosition:animated:, cellForRowAtIndexPath:, and indexPathForSelectedRow methods.
Declared In
UITableView.h
Table Cell Insertion and Deletion Animation
The type of animation when rows are inserted or deleted.
typedef enum {
UITableViewRowAnimationFade,
UITableViewRowAnimationRight,
UITableViewRowAnimationLeft,
UITableViewRowAnimationTop,
UITableViewRowAnimationBottom,
UITableViewRowAnimationNone,
UITableViewRowAnimationMiddle,
UITableViewRowAnimationAutomatic = 100
} UITableViewRowAnimation;
Constants
UITableViewRowAnimationFade
The inserted or deleted row or rows fades into or out of the table view.
Available in iOS 2.0 and later.
Declared in UITableView.h.
UITableViewRowAnimationRight
The inserted row or rows slides in from the right; the deleted row or rows slides out to the right.
Available in iOS 2.0 and later.
Declared in UITableView.h.
UITableViewRowAnimationLeft
The inserted row or rows slides in from the left; the deleted row or rows slides out to the left.
Available in iOS 2.0 and later.
Declared in UITableView.h.
UITableViewRowAnimationTop
The inserted row or rows slides in from the top; the deleted row or rows slides out toward the top.
Available in iOS 2.0 and later.
Declared in UITableView.h.
UITableViewRowAnimationBottom
The inserted row or rows slides in from the bottom; the deleted row or rows slides out toward the bottom.
Available in iOS 2.0 and later.
Declared in UITableView.h.
UITableViewRowAnimationNone
No animation is performed. The new cell value appears as if the cell had just been reloaded.
Available in iOS 3.0 and later.
Declared in UITableView.h.
UITableViewRowAnimationMiddle
The table view attempts to keep the old and new cells centered in the space they did or will occupy. Available in iPhone 3.2.
Available in iOS 3.2 and later.
Declared in UITableView.h.
UITableViewRowAnimationAutomatic
The table view chooses an appropriate animation style for you. (Introduced in iOS 5.0.)
Available in iOS 5.0 and later.
Declared in UITableView.h.
Discussion
You specify one of these constants as a parameter of the insertRowsAtIndexPaths:withRowAnimation:, insertSections:withRowAnimation:, deleteRowsAtIndexPaths:withRowAnimation:,deleteSections:withRowAnimation:, reloadRowsAtIndexPaths:withRowAnimation:, and reloadSections:withRowAnimation: methods.
Declared In
UITableView.h
Section Index Icons
Requests icon to be shown in the section index of a table view.
UIKIT_EXTERN NSString *const UITableViewIndexSearch;
Constants
UITableViewIndexSearch
If the data source includes this constant string in the array of strings it returns in sectionIndexTitlesForTableView:, the section index displays a magnifying glass icon at the corresponding index location. This location should generally be the first title in the index.
Available in iOS 3.0 and later.
Declared in UITableView.h.
Declared In
UITableView.h
Default Dimension
The default value for a given dimension.
UIKIT_EXTERN const CGFloat UITableViewAutomaticDimension;
Constants
UITableViewAutomaticDimension
Requests that UITableView use the default value for a given dimension.
Available in iOS 5.0 and later.
Declared in UITableView.h.
Discussion
You return this value from UITableViewDelegate methods that request dimension metrics when you want UITableView to choose a default value. For example, if you return this constant in the tableView:heightForHeaderInSection: or tableView:heightForFooterInSection:, UITableView uses a height that fits the value returned from tableView:titleForHeaderInSection: or tableView:titleForFooterInSection: (if the title is not nil).
Declared In
UITableView.h
Notifications
UITableViewSelectionDidChangeNotification
Posted when the selected row in the posting table view changes.
There is no userInfo dictionary associated with this notification.
Availability
- Available in iOS 2.0 and later.
Declared In
UITableView.h
© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-12)
Did this document help you? Yes It's good, but... Not helpful...
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
