iOS Guides | Samples

MonoTouch.UIKit.UITableView Class

A table view is used to display and edit hierarchical lists of information. A UITableView is limited to a single column because it is designed for a small screen.

See Also: UITableView

Syntax

[MonoTouch.Foundation.Register("UITableView", true)]
public class UITableView : UIScrollView, IUIDataSourceTranslating, IUISpringLoadedInteractionSupporting, IDisposable

See Also

Remarks

UITableView is a subclass of UIScrollView that allows users to scroll the table vertically (the closely-related UICollectionView class allows for horizontal scrolling and complex two-dimensional layouts). The table consists of UITableViewCell objects that are used to render the rows of the table. These cells have content -- labels, images, etc. -- and can also show accessories such as disclosure arrows or inputs controls. UITableViews can enter an edit-mode in which rows can be inserted, deleted, and reordered.

The Xamarin article

Working with Tables provides guidance on all aspects of UITableView use.

For most use-cases, it is not necessary for application developers to subclass UITableView or UITableViewController, which provide the generic table behavior. Instead, application developers will generally subclass UITableViewSource to populate a table and, often, UITableViewCell to customize appearance and row behavior.

Table Parts and Functionality

Classes Overview

The primary classes used to display table views are:

ClassResponsibility
UITableView A view that contains a collection of cells inside a scrolling container. The table view typically uses the entire screen in an iPhone app but may exist as part of a larger view on the iPad (or appear in a popover).
UITableViewCell A view that represents a single cell (or row) in a table view. There are four built-in cell types and it is possible to create custom cells both in C# or with Interface Builder.
UITableViewSource Xamarin.iOS-exclusive abstract class that provides all the methods required to display a table, including row count, returning a cell view for each row, handling row selection and many other optional features. You must subclass this to get a UITableView working. (UITableViewSource combines UITableViewDataSource and UITableViewDelegate. These classes are still available if the application developer chooses not to use UITableViewSource.)
NSIndexPath Contains Row and Section properties that uniquely identify the position of a cell in a table.
UITableViewController A ready-to-use UIViewController that has a UITableView hardcoded as its view and made accessible via the UITableViewController.TableView property.
UIViewController If the table does not occupy the entire screen you can add a UITableView to any UIViewController with its UIView.Frame property set appropriately.

Components of a UITableView

There are two UITableViewStyle styles: Plain and Grouped. The Plain style allows the section headers and footers to remain visible as the section is scrolled through, and can optionally support an index that appears along the right edge to quickly scroll to a specific section. The Grouped style displays sections in rounded-rectangles that visually group the rows, and provides a default background image behind the scrolling list. The style of the UITableView is specified as an argument to the UITableView.UITableView(RectangleF,UITableViewStyle) constructor and cannot be changed. Grouped tables should not provide an index.

Tables consist of the following parts:

ElementAccessed via:Type
Table HeaderUITableView.TableHeaderViewUIView
Section HeaderUITableViewSource.GetViewForHeaderUITableViewHeaderFooterView
Cells (also called Rows)UITableViewSource.GetCellUITableViewCell
Section FooterUITableViewSource.GetViewForFooterUITableViewHeaderFooterView
IndexUITableViewSource.SectionIndexTitlesstring[]
Edit mode (includes ‘swipe to delete’ and drag handles to change row order)
Table FooterUITableView.TableFooterViewUIView

Section rows, headers, footers, edit controls and the index are displayed as follows:

Populating Table Cells

UITableViews are designed to work efficiently with tables with thousands of rows. In order to achieve this, each UITableView maintains a reusable cache of UITableViewCells only a few items larger than can be shown on the screen at any given time.

A UITableViewSource object is responsible for managing the relationship between the relatively few UITableViewCells and the data is to be displayed. The UITableViewSource's UITableViewSource.NumberOfSections and UITableViewSource.RowsInSection methods allow the UITableView to request only the data necessary for the cells on the screen. A specific cell is identified by an NSIndexPath, whose NSIndexPath.Section and NSIndexPath.Rowproperties will specify a unique cell.

As cells are about to be scrolled onto the screen, the UITableView automatically calls the UITableViewSource.GetCell method of the UITableViewSource object assigned to the UITableView.Source property of the UITableView (or, if the application developer prefers, the UITableViewDataSource.GetRow method of the UITableViewDataSource object referred to by the UITableView.DataSource property).

The application developer's responsibilities when overriding UITableViewSource.GetCell changed with the introduction of iOS 6. Application developers targeting iOS 6 and later should register a UITableViewCell for reuse with the UITableView by calling either the UITableView.RegisterClassForCellReuse or UITableView.RegisterNibForCellReuse method. Once that is done, application developers do not need to check for null in their override of the UITableViewSource.GetCell method.

If application developers are using the UITableView.RegisterClassForCellReuse with their own subclass of UITableViewCell, that implementation must override the UITableViewCell.UITableViewCell(IntPtr) constructor and call the base constructor (i.e., MyTableViewCell(IntPtr handle) : base(handle){}).

The application developer overrides the UITableViewSource.GetCell method so that it:

Since the UITableViewSource.GetCell method will be called whenever a cell comes into view, application developers should avoid unnecessary computation.

The UITableView's reuse queue is accessed via the UITableView.DequeueReusableCell method, which takes a string identifying the type of UITableViewCell to retrieve. In iOS 5 and earlier, that method may return null, in which case the application developer should instantiate a new UITableViewCell. In iOS 6 and later, while initializing the UITableView, the application developer must use either UITableView.RegisterClassForCellReuse or UITableView.RegisterNibForCellReuse to associate a UITableViewCell type and it's reuse identifier so that the method UITableViewSource.GetCell can instantiate instances as necessary.

The following shows a simple example of the UITableViewSource.GetCell method:

C# Example

          public override UITableViewCell GetCell (UITableView tableView, NSIndexPath indexPath)
          {
          //Attempt to retrieve previously-allocated cell
          var cell = tableView.DequeueReusableCell (this.cellTypeIdentifier);
          //The following check and code-block only necessary in applications that do not use RegisterClassforCellReuse or RegisterNibForCellReuse
          if (cell == null) {
          //No reusable cell, so initialize a new one
          cell = new UITableViewCell (UITableViewCellStyle.Default, this.cellTypeIdentifier);
          cell.Tag = Environment.TickCount;
          }
          
          // Change the state of the cell
          cell.TextLabel.Text = //...etc...
          
          // return the cell
          return cell;
          }

Customizing Table Appearance

Other than the UITableView.Style property that specifies whether a UITableView is grouped or continuous, the appearance of the table is primarily determined by the UITableViewCells, the UITableViewHeaderFooterViews used for section headers and footers, and the UIViews used for the UITableView.Header and UITableView.Footer properties. The API documentation for UITableViewCell describes customization in detail.

Highlighting and Selection

Selecting and highlighting in a UITableView follows this sequence:

User ActionUITableViewDelegate (UITableViewSource) MethodsUITableViewCell Properties
Nothing touchedHighlighted == false; Selected == false
Finger down in cellUITableViewDelegate.ShouldHighlightRow is called. If it returns false, processing stops.
UITableViewSource.RowHighlighted is called. Highlighted == true; Selected == false
Finger upUITableViewDelegate.WillSelectRow is called. If it returns null, processing stops. Otherwise, whatever NSIndexPath it returns will be highlighted.
UITableViewDelegate.RowSelected is called. UITableViewDelegate.RowUnhighlighted is called. Highlighted == false; Selected == true

Deselecting a UITableViewCell follows a similar sequence:

User ActionUITableViewDelegate (UITableViewSource) MethodsUITableViewCell Properties
Nothing touched while some UITableViewCell is highlighted.Highlighted == false; Selected == true
Finger taps cell (Deselect gesture)UITableViewDelegate.WillDeselectRow is called. If it returns null, processing stops. Otherwise, whatever NSIndexPath is returned will be deselected.
UITableViewDelegate.RowDeselected is called. Highlighted == false; Selected == false
Note:

UITableView caches UITableViewCell objects only for visible rows, but caches the heights of rows, headers and footers for the entire table. It is possible to create custom UITableViewCell objects with varying heights and custom layouts.

UITableView overrides UIView.LayoutSubviews so that it calls UITableView.ReloadData only when you create a new instance or when you assign a new UITableView.Source (or UITableView.DataSource).Reloading the table view clears current state (including the current selection). However if you explicitly call UITableView.ReloadData it clears this state and any subsequent direct or indirect call to UIView.LayoutSubviews does not trigger a reload.

Related content

Requirements

Namespace: MonoTouch.UIKit
Assembly: monotouch (in monotouch.dll)
Assembly Versions: 0.0.0.0

The members of MonoTouch.UIKit.UITableView are listed below.

See Also: UIScrollView

Public Constructors

Default constructor that initializes a new instance of this class with no parameters.
A constructor that initializes the object from the data stored in the unarchiver object.
Constructor to call on derived classes to skip initialization and merely allocate the object.
Initializes the UITableView with the specified frame.
A constructor used when creating managed representations of unmanaged objects; Called by the runtime.
Creates a table view with the given UITableView.Frame and UITableViewStyle.

Public Properties

AllowsMultipleSelectionBoolean. Whether more than one row can be selected (outside of editing mode).
AllowsMultipleSelectionDuringEditingBoolean. Whether more than one row can be selected while in editing mode.
AllowsSelectionBoolean. Whether a row can be selected.
AllowsSelectionDuringEditingBoolean. Whether a row can be selected while in editing mode.
[read-only]
static
AppearanceUITableView+UITableViewAppearance. Strongly-typed property that returns the UIAppearance class for this class.
[read-only]
static
AutomaticDimensionSingle. Represents the value associated with the constant UITableViewAutomaticDimension
BackgroundViewUIView. The background view of the table.
CellLayoutMarginsFollowReadableWidthBoolean. Whether the layout margins of the cell's contents are set by the system to have a comfortable, legible width for the user.
[read-only]
override
ClassHandleIntPtr. The handle for this class.
DataSourceUITableViewDataSource. The object that acts as the data source for the table view.
DelegateUITableViewDelegate. An instance of the MonoTouch.UIKit.UITableViewDelegate model class which acts as the class delegate.
EditingBoolean. Whether the table view is in editing mode.
EstimatedRowHeightSingle. The estimated height of individual rows in this UITableView.
EstimatedSectionFooterHeightSingle. The estimated height of section foots in this UITableView.
EstimatedSectionHeaderHeightSingle. The estimated height of section headers in this UITableView.
[read-only]
IndexPathForSelectedRowNSIndexPath. The NSIndexPath for the currently-selected row.
[read-only]
IndexPathsForSelectedRowsNSIndexPath[]. An array of NSIndexPaths for the selected rows.
[read-only]
IndexPathsForVisibleRowsNSIndexPath[]. An array of NSIndexPaths for the set of currently-visible rows.
[read-only]
static
IndexSearchNSString. Represents the value associated with the constant UITableViewIndexSearch
PrefetchDataSourceIUITableViewDataSourcePrefetching. Gets or sets the prefetch-capable source for this collection view.
RemembersLastFocusedIndexPathBoolean. Gets or sets a Boolean value that controls whther the table view will return focus to the most recently focused index path.
RowHeightSingle. The height of each row in this UITableView.
SectionFooterHeightSingle. The height of section foots in this UITableView.
SectionHeaderHeightSingle. The height of section headers in this UITableView.
SectionIndexBackgroundColorUIColor. The color used for the background of this UITableView's section index when it is not being touched.
SectionIndexColorUIColor. The color used for the index text of this UITableView.
SectionIndexMinimumDisplayRowCountInt32. The number of rows required in a table view before the index list is displayed.
SectionIndexTrackingBackgroundColorUIColor. Specifies the background color of the index as the application user drags.
[read-only]
static
SelectionDidChangeNotificationNSString. Notification constant for SelectionDidChange
SeparatorColorUIColor. The color of the separator between rows in the table view.
SeparatorEffectUIVisualEffect. The UIVisualEffect to be used on table separators.
SeparatorInsetUIEdgeInsets. The default inset of cell separators.
SeparatorStyleUITableViewCellSeparatorStyle. The style of the separator between rows in the table view.
SourceUITableViewSource. A MonoTouch-specific feature that uses a UITableViewSource subclass to act as both UITableView.Delegate or UITableView.DataSource.
[read-only]
StyleUITableViewStyle. Returns the style of the table view (read-only).
TableFooterViewUIView. Returns a view that is displayed below the table view.
TableHeaderViewUIView. Returns a view that is displayed above the table view.
[read-only]
VisibleCellsUITableViewCell[]. Returns an array of UITableViewCell that are currently visible in the table view.
WeakDataSourceNSObject. The data source for this UITableView.
WeakDelegateNSObject. An object that can respond to the delegate protocol for this type

Public Methods

static
AppearanceWhenContainedIn(params Type[]) : UITableView+UITableViewAppearance
Returns a strongly typed UIAppearance for instances of this class when the view is hosted in the specified hierarchy.
BeginUpdates()
Call this method before inserting, updating or selecting rows that should be animated as one operation. UITableView.EndUpdates must be called after the modifications are complete.
CellAt(NSIndexPath) : UITableViewCell
Returns the table cell at the specified index path.
DeleteRows(NSIndexPath[], UITableViewRowAnimation)
Delete the rows referenced in the atIndexPaths array. The deletion can optionally be animated.
DeleteSections(NSIndexSet, UITableViewRowAnimation)
Deletes a section (or sections) from a table view, with an option to animate the operation.
DequeueReusableCell(NSString) : UITableViewCell
Returns a reusable table view cell that was created with the given ReuseIdentifier.
DequeueReusableCell(String) : UITableViewCell
Returns a reusable table view cell that was created with the given ReuseIdentifier.
DequeueReusableCell(NSString, NSIndexPath) : UITableViewCell
Returns a reusable table view cell for the given reuseIdentifier, properly sized for the indexPath.
DequeueReusableCell(String, NSIndexPath) : UITableViewCell
Returns a reusable cell identified by reuseIdentifier and located at indexPath.
DequeueReusableHeaderFooterView(NSString) : UITableViewHeaderFooterView
Returns a reusable UITableViewHeaderFooterView for the given reuseIdentifier.
DequeueReusableHeaderFooterView(String) : UITableViewHeaderFooterView
Returns a reusable header/footer view identified by reuseIdentifier
DeselectRow(NSIndexPath, Boolean)
Deselect a given row in a table view, with an option to animate the deselection.
EndUpdates()
Finalize a series of method calls that insert, update or select rows to animate as one operation. UITableView.BeginUpdates must be called before the modifications are made.
static
GetAppearance(UITraitCollection) : UITableView+UITableViewAppearance
Gets an appearance object for the specified traits.
static
GetAppearance(UITraitCollection, params Type[]) : UITableView+UITableViewAppearance
Returns an appearance object that is derived by merging traits from containers.
static
GetAppearance<T>() : UITableView+UITableViewAppearance
Obtains the appearance proxy UITableViewAppearance for the subclass of UITableView.
static
GetAppearance<T>(UITraitCollection) : UITableView+UITableViewAppearance
Obtains the appearance proxy UITableViewAppearance for the subclass of UITableView.
static
GetAppearance<T>(UITraitCollection, params Type[]) : UITableView+UITableViewAppearance
Obtains the appearance proxy UITableViewAppearance for the subclass of UITableView that has the specified trait collection when the view is hosted in the specified hierarchy.
GetFooterView(Int32) : UITableViewHeaderFooterView
The footer view for the specified section.
GetHeaderView(Int32) : UITableViewHeaderFooterView
Returns the UITableViewHeaderFooterView for the specified section. Returns null if there is no corresponding view.
IndexPathForCell(UITableViewCell) : NSIndexPath
Calculates the index path for the specified cell.
IndexPathForRowAtPoint(PointF) : NSIndexPath
Returns the NSIndexPath for the row at the indicated point.
InsertRows(NSIndexPath[], UITableViewRowAnimation)
Inserts rows into the UITableView.
InsertSections(NSIndexSet, UITableViewRowAnimation)
Inserts a section (or sections) from a table view, with an option to animate the operation.
MoveRow(NSIndexPath, NSIndexPath)
Moves a row from fromIndexPath to toIndexPath.
MoveSection(Int32, Int32)
Moves a section to a new location in the table view.
NumberOfRowsInSection(Int32) : Int32
Returns the number of rows (table cells) in a given section.
NumberOfSections() : Int32
Returns the number of sections in the table view.
RectForFooterInSection(Int32) : RectangleF
Returns the drawing area for the specified section's footer.
RectForHeaderInSection(Int32) : RectangleF
Returns the drawing area for the specified section's header.
RectForRowAtIndexPath(NSIndexPath) : RectangleF
Returns the drawing area for the specified row.
RectForSection(Int32) : RectangleF
Returns the drawing area for the specified section.
RegisterClassForCellReuse(Type, NSString)
Registers a type to provide UITableViewCells for a specific reuseIdentifier.
RegisterClassForCellReuse(Type, String)
Registers the cellType type for reuse, keyed by the identifier reuseIdentifier.
RegisterClassForHeaderFooterViewReuse(Type, NSString)
Registers a type to provide UIViews for headers or footers for a specific reuseIdentifier.
RegisterClassForHeaderFooterViewReuse(Type, String)
Registers the cellType type for reuse, keyed by the identifier reuseIdentifier.
RegisterNibforCellReuse(UINib, String)
Registers a nib object (containing a UITableViewCell) with the given identifer string.
RegisterNibForCellReuse(UINib, NSString)
Specifies the nib file to use for cells with the specified identifier.
RegisterNibForCellReuse(UINib, String)
Registers a nib object (containing a UITableViewCell) with the given identifer string.
RegisterNibForHeaderFooterViewReuse(UINib, NSString)
Specifies the nib file to use for headers or footers.
RegisterNibForHeaderFooterViewReuse(UINib, String)
Registers a nib object (containing a UITableViewHeaderFooterView) with the given identifier string.
ReloadData()
Reloads the rows and sections in the table view.
ReloadRows(NSIndexPath[], UITableViewRowAnimation)
Reloads specific rows with the given animation effect.
ReloadSectionIndexTitles()
Reloads the index bar long the right edge of a table view.
ReloadSections(NSIndexSet, UITableViewRowAnimation)
Reloads specific sections with an animation effect.
ScrollToNearestSelected(UITableViewScrollPosition, Boolean)
Automatically scrolls the rows so that the selected row nearest to a given position is moved to that position.
ScrollToRow(NSIndexPath, UITableViewScrollPosition, Boolean)
Automatically scrolls the table view until the specified row appears in the required position.
SelectRow(NSIndexPath, Boolean, UITableViewScrollPosition)
Selects the given row, optionall scrolling the row to a specific location.
SetEditing(Boolean, Boolean)
Turns editing mode on or off.

Protected Methods

override
Dispose(Boolean)
Releases the resources used by the UITableView object.