Monday, 26 August 2013

Introduction to UITableView

Why we are using UITableView ?



It displays a single-column list of multiple rows through which users can scroll. Each row in a table view is a UITableViewCell object. The plain style table view displays rows that occupy the full width of the view and can display optional headers and footers for arbitrary sections of rows and for the table as a whole. The grouped style table view displays distinct groups of rows inset from the edges of the view and can display optional headers and footers between groups. A user can edit a table by inserting, deleting, and reordering table cells.




Output of the example code show in below image




Programmatically create a UITableview 


@interface ViewController ()
{
    UITableView *tableView;
    NSArray *arraySample;
}
@end


- (void)viewDidLoad
{
    [super viewDidLoad];
    CGRect tableframe=CGRectMake(5,5,300,400);
   tableView = [[UITableView alloc]initWithFrame:tableframe style:UITableViewStylePlain];
    
    tableView.rowHeight = 45;
    tableView.sectionFooterHeight = 22;
    tableView.sectionHeaderHeight = 22;
    tableView.scrollEnabled = YES;
    tableView.showsVerticalScrollIndicator = YES;
    tableView.userInteractionEnabled = YES;
    tableView.bounces = YES;
    
    tableView.delegate = self;
    tableView.dataSource = self;
    [self.view addSubview:tableView];
     arraySample=[[NSArray alloc]initWithObjects:@"Apple",@"Orange",@"Grape",@"Banana",@"PineApple",nil];

}


- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView
{
    return 1;    //count of section
}



- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {

    
    return [arraySample count];    //count number of rows

}



- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    static NSString *CellIdentifier = @"newFriendCell";

    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
    
    if (cell == nil) {

       cell = [[UITableViewCell alloc]initWithStyle:UITableViewCellStyleSubtitle reuseIdentifier:CellIdentifier];
   
}
    
   cell.textLabel.text=[arraySample objectAtIndex:indexPath.row];
   cell.textLabel.textColor = [UIColor lightGrayColor];
    
   return cell;
}

-(void)tableView:(UITableView *)tableView didDeselectRowAtIndexPath:(NSIndexPath *)indexPath
{
    
}








Below contents are from Apple Docs


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 manages table row configuration and selection, row reordering, highlighting, accessory views, and editing operations.
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 for visible rows. 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.
For information about basic view behaviors, see View Programming Guide for iOS.

State Preservation

In iOS 6 and later, if you assign a value to this view’s restorationIdentifier property, it attempts to preserve the currently selected rows and the first visible row. Preservation of these items is only possible if the table’s data source adopts the UIDataSourceModelAssociation protocol, which provides a way to identify a row’s contents independent of that row’s position in the table. During restoration, the table restores the previous selection and first visible row for any rows that are still vended by the data source.
For more information about how state preservation and restoration works, see iOS App Programming Guide.

Tasks

Initializing a UITableView Object

Configuring a Table View

Creating Table View Cells

Accessing Header and Footer Views

Accessing Cells and Sections

Scrolling the Table View

Managing Selections

Inserting, Deleting, and Moving Rows and Sections

Managing the Editing of Table Cells

Reloading the Table View

Accessing Drawing Areas of the Table View

Managing the Delegate and the Data Source

Configuring the Table Index

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
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
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
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
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.
Assigning an opaque view to this property obscures the background color set on the table view itself.
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
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
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
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
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
Declared In
UITableView.h

sectionIndexColor

The color to use for the table view’s index text.
@property(nonatomic, retain) UIColor *sectionIndexColor
Discussion
Table views can display an index along the side of the view, making it easier for users to navigate the contents of the table quickly. This property specifies the color to use for text displayed in this region.
Availability
  • Available in iOS 6.0 and later.
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 zero.
Availability
  • Available in iOS 2.0 and later.
Declared In
UITableView.h

sectionIndexTrackingBackgroundColor

The color to use for the table view’s index background area.
@property(nonatomic, retain) UIColor *sectionIndexTrackingBackgroundColor
Discussion
Table views can display an index along the side of the view, making it easier for users to navigate the contents of the table quickly. This property specifies the color to display in the background of the index when the user drags a finger through it.
Availability
  • Available in iOS 6.0 and later.
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
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
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
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
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
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
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
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. This parameter must not be nil.
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 data source has marked for reuse. Call this method from your data source object when asked to provide a new cell for the table view. This method dequeues an existing cell if one is available or creates a new one using the class or nib file you previously registered. If no cell is available for reuse and you did not register a class or nib file, this method returns nil.
If you registered a class for the specified identifier and a new cell must be created, this method initializes the cell by calling its initWithStyle:reuseIdentifier: method. For nib-based cells, this method loads the cell object from the provided nib file. If an existing cell was available for reuse, this method calls the cell’s prepareForReuse method instead.
Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITableView.h

dequeueReusableCellWithIdentifier:forIndexPath:

Returns a reusable table-view cell object for the specified reuse identifier.
- (id)dequeueReusableCellWithIdentifier:(NSString *)identifier forIndexPath:(NSIndexPath *)indexPath
Parameters
identifier
A string identifying the cell object to be reused. This parameter must not be nil.
indexPath
The index path specifying the location of the cell. The data source receives this information when it is asked for the cell and should just pass it along. This method uses the index path to perform additional configuration based on the cell’s position in the table view.
Return Value
A UITableViewCell object with the associated reuse identifier. This method always returns a valid cell.
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 data source has marked for reuse. Call this method from your data source object when asked to provide a new cell for the table view. This method dequeues an existing cell if one is available or creates a new one based on the class or nib file you previously registered.
If you registered a class for the specified identifier and a new cell must be created, this method initializes the cell by calling its initWithStyle:reuseIdentifier: method. For nib-based cells, this method loads the cell object from the provided nib file. If an existing cell was available for reuse, this method calls the cell’s prepareForReuse method instead.
Availability
  • Available in iOS 6.0 and later.
Related Sample Code
Declared In
UITableView.h

dequeueReusableHeaderFooterViewWithIdentifier:

Returns a reusable header or footer view located by its identifier.
- (id)dequeueReusableHeaderFooterViewWithIdentifier:(NSString *)identifier
Parameters
identifier
A string identifying the header or footer view to be reused. This parameter must not be nil.
Return Value
A UITableViewHeaderFooterView object with the associated identifier or nil if no such object exists in the reusable view queue.
Discussion
For performance reasons, a table view'€™s delegate should generally reuse UITableViewHeaderFooterView objects when it is asked to provide them. A table view maintains a queue or list of UITableViewHeaderFooterView objects that the table view's delegate has marked for reuse. It marks a view for reuse by assigning it a reuse identifier when it creates it (that is, in the initWithReuseIdentifier: method of UITableViewHeaderFooterView).
You can use this method to access specific template header and footer views that you previously created. You can access a view'€™s reuse identifier through its reuseIdentifier property.
Availability
  • Available in iOS 6.0 and later.
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
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

footerViewForSection:

Returns the footer view associated with the specified section.
- (UITableViewHeaderFooterView *)footerViewForSection:(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 footer view associated with the section or nil if the section does not have a footer view.
Availability
  • Available in iOS 6.0 and later.
Declared In
UITableView.h

headerViewForSection:

Returns the header view associated with the specified section.
- (UITableViewHeaderFooterView *)headerViewForSection:(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 header view associated with the section or nil if the section does not have a header view.
Availability
  • Available in iOS 6.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
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
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
Related Sample Code
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
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
Related Sample Code
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
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
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
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 position. 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
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 position. 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
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
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
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

registerClass:forCellReuseIdentifier:

Registers a class for use in creating new table cells.
- (void)registerClass:(Class)cellClass forCellReuseIdentifier:(NSString *)identifier
Parameters
cellClass
The class of a cell that you want to use in the table.
identifier
The reuse identifier for the cell. This parameter must not be nil and must not be an empty string.
Discussion
Prior to dequeueing any cells, call this method or the registerNib:forCellReuseIdentifier: method to tell the table view how to create new cells. If a cell of the specified type is not currently in a reuse queue, the table view uses the provided information to create a new cell object automatically.
If you previously registered a class or nib file with the same reuse identifier, the class you specify in the cellClass parameter replaces the old entry. You may specify nil for cellClass if you want to unregister the class from the specified reuse identifier.
Availability
  • Available in iOS 6.0 and later.
Declared In
UITableView.h

registerClass:forHeaderFooterViewReuseIdentifier:

Registers a class for use in creating new table header or footer views.
- (void)registerClass:(Class)aClass forHeaderFooterViewReuseIdentifier:(NSString *)identifier
Parameters
aClass
The class of a header or footer view that you want to use in the table.
identifier
The reuse identifier for the header or footer view. This parameter must not be nil and must not be an empty string.
Discussion
Prior to dequeueing any header or footer views, call this method or the registerNib:forHeaderFooterViewReuseIdentifier: method to tell the table view how to create new instances of your views. If a view of the specified type is not currently in a reuse queue, the table view uses the provided information to create a one automatically.
If you previously registered a class or nib file with the same reuse identifier, the class you specify in the cellClass parameter replaces the old entry. You may specify nil for cellClass if you want to unregister the class from the specified reuse identifier.
Availability
  • Available in iOS 6.0 and later.
See Also
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 that specifies the nib file to use to create the cell. This parameter cannot be nil.
identifier
The reuse identifier for the cell. This parameter must not be nil and must not be an empty string.
Discussion
Prior to dequeueing any cells, call this method or the registerClass:forCellReuseIdentifier: method to tell the table view how to create new cells. If a cell of the specified type is not currently in a reuse queue, the table view uses the provided information to create a new cell object automatically.
If you previously registered a class or nib file with the same reuse identifier, the nib you specify in the nib parameter replaces the old entry. You may specify nil for nib if you want to unregister the nib from the specified reuse identifier.
Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
UITableView.h

registerNib:forHeaderFooterViewReuseIdentifier:

Registers a nib object containing a header or footer with the table view under a specified identifier.
- (void)registerNib:(UINib *)nib forHeaderFooterViewReuseIdentifier:(NSString *)identifier
Parameters
nib
A nib object that specifies the nib file to use to create the header or footer view. This parameter cannot be nil.
identifier
The reuse identifier for the header or footer view. This parameter must not be nil and must not be an empty string.
Discussion
Prior to dequeueing any header or footer views, call this method or the registerClass:forHeaderFooterViewReuseIdentifier: method to tell the table view how to create new instances of your views. If a view of the specified type is not currently in a reuse queue, the table view uses the provided information to create a new one automatically.
If you previously registered a class or nib file with the same reuse identifier, the nib you specify in the nib parameter replaces the old entry. You may specify nil for nib if you want to unregister the nib from the specified reuse identifier.
Availability
  • Available in iOS 6.0 and later.
See Also
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
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
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
Related Sample Code
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
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” for 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
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:UITableViewScrollPositionNone animated:YES];
Availability
  • Available in iOS 2.0 and later.
See Also
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
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
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
Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)