UITableViewCell Class Reference

Properties

For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.

accessoryAction

The selector defining the action message to invoke when users tap the accessory view. (Deprecated. Instead use the tableView:commitEditingStyle:forRowAtIndexPath: or tableView:accessoryButtonTappedForRowWithIndexPath: for handling taps on cells.)

@property(nonatomic) SEL accessoryAction

Discussion

If you specify a selector for the accessory action, a message is sent only if the accessory view is a detail disclosure button—that is, the cell's accessoryType property is assigned a value ofUITableViewCellAccessoryDetailDisclosureButton. If the value of this property is NULL, no action message is sent.

The accessory view is a UITableViewCell-defined control, framework control, or custom control on the right side of the cell. It is often used to display a new view related to the selected cell. If the accessory view inherits from UIControl, you may set a target and action through the addTarget:action:forControlEvents: method. See accessoryView for more information.

See Also

•   @property target
•   @property editAction

accessoryType

The type of standard accessory view the cell should use (normal state).

@property(nonatomic) UITableViewCellAccessoryType accessoryType

Discussion

The accessory view appears in the the right side of the cell in the table view’s normal (default) state. The standard accessory views include the disclosure chevron; for a description of valid accessoryType constants, see “Cell Accessory Type.” The default is UITableViewCellAccessoryNone. If a custom accessory view is set through the accessoryView property, the value of this property is ignored. If the cell is enabled and the accessory type is UITableViewCellAccessoryDetailDisclosureButton, the accessory view tracks touches and, when tapped, sends the data-source object a tableView:accessoryButtonTappedForRowWithIndexPath: message.

The accessory-type image cross-fades between normal and editing states if it set for both states; use the editingAccessoryType property to set the accessory type for the cell during editing mode. If this property is not set for both states, the cell is animated to slide in or out, as necessary.

See Also

•   @property editingAccessoryType
•   @property editingAccessoryView
• – willTransitionToState:
• – didTransitionToState:

Related Sample Code

• BonjourWeb
• DrillDownSave
• iPhoneCoreDataRecipes
• TaggedLocations
• TheElements

accessoryView

A view that is used, typically as a control, on the right side of the cell (normal state).

@property(nonatomic, retain) UIView *accessoryView

Discussion

If the value of this property is not nil, the UITableViewCell class uses the given view for the accessory view in the table view’s normal (default) state; it ignores the value of the accessoryType property. The provided accessory view can be a framework-provided control or label or a custom view. The accessory view appears in the the right side of the cell.

The accessory view cross-fades between normal and editing states if it set for both states; use the editingAccessoryView property to set the accessory view for the cell during editing mode. If this property is not set for both states, the cell is animated to slide in or out, as necessary.

See Also

•   @property editingAccessoryType
•   @property editingAccessoryView
• – willTransitionToState:
• – didTransitionToState:

Related Sample Code

• Accessory
• BatteryStatus
• BonjourWeb
• WiTap

backgroundView

The view used as the background of the cell.

@property(nonatomic, retain) UIView *backgroundView

Discussion

The default is nil for cells in plain-style tables (UITableViewStylePlain) and non-nil for grouped-style tables UITableViewStyleGrouped). UITableViewCell adds the background view as a subview behind all other views and uses its current frame location.

See Also

•   @property contentView
•   @property selectedBackgroundView

Related Sample Code

• AdvancedTableViewCells

contentView

Returns the content view of of the cell object. (read-only)

@property(nonatomic, readonly, retain) UIView *contentView

Discussion

The content view of a UITableViewCell object is the default superview for content displayed by the cell. If you want to customize cells by simply adding additional views, you should add them to the content view so they will be positioned appropriately as the cell transitions into and out of editing mode.

See Also

•   @property backgroundView

Related Sample Code

• GenericKeychain
• iPhoneCoreDataRecipes
• LocateMe
• Reflection
• SeismicXML

detailTextLabel

Returns the secondary label of the table cell if one exists. (read-only)

@property(nonatomic, readonly, retain) UILabel *detailTextLabel

Discussion

Holds the secondary (or detail) label of the cell. UITableViewCell adds an appropriate label when you create the cell in a style that supports secondary labels. If the style doesn’t support detail labels, nil is returned. See “Cell Styles” for descriptions of the main label in currently defined cell styles.

See Also

•   @property textLabel
• – initWithStyle:reuseIdentifier:

Related Sample Code

• LocateMe
• NavBar
• Reflection
• TopSongs
• XMLPerformance

editAction

The selector defining the action message to invoke when users tap the insert or delete button. (Deprecated. Instead use the tableView:commitEditingStyle:forRowAtIndexPath: or tableView:accessoryButtonTappedForRowWithIndexPath: for handling taps on cells.)

@property(nonatomic) SEL editAction

Discussion

When the cell'€™s table is in editing mode, the cell displays a green insert control or a red delete control to the left of it. (The selectedBackgroundView constant applied to the cell via the editingStyle property determines which control is used.) Typically, the associated UITableView object sets the editing action for all cells; you can use this property to alter the editing action for individual cells. If the value of this property is NULL, no action message is sent.

See Also

•   @property target
•   @property accessoryAction

editing

A Boolean value that indicates whether the cell is in an editable state.

@property(nonatomic, getter=isEditing) BOOL editing

Discussion

When a cell is in an editable state, it displays the editing controls specified for it: the green insertion control, the red deletion control, or (on the right side) the reordering control. Use editingStyle and showsReorderControl to specify these controls for the cell.

Related Sample Code

• iPhoneCoreDataRecipes
• TaggedLocations

editingAccessoryType

The type of standard accessory view the cell should use in the table view’s editing state.

@property(nonatomic) UITableViewCellAccessoryType editingAccessoryType

Discussion

The accessory view appears in the the right side of the cell when the table view is in editing mode. The standard accessory views include the disclosure chevron; for a description of valid constants, see “Cell Accessory Type.” The default is UITableViewCellAccessoryNone. If a custom accessory view for editing mode is set through the editingAccessoryView property, the value of this property is ignored. If the cell is enabled and the accessory type is UITableViewCellAccessoryDetailDisclosureButton, the accessory view tracks touches and, when tapped, sends the delegate object a tableView:accessoryButtonTappedForRowWithIndexPath: message.

The accessory type cross-fades between normal and editing states if it set for both states; use the accessoryType property to set the accessory view for the cell during the table view’s normal state. If this property is not set for both states, the cell is animated to slide or out, as necessary.

See Also

•   @property accessoryType
•   @property accessoryView
• – willTransitionToState:
• – didTransitionToState:

Related Sample Code

• CoreDataBooks
• iPhoneCoreDataRecipes
• SimpleUndo

editingAccessoryView

A view that is used typically as a control on the right side of the cell when it is in editing mode.

@property(nonatomic, retain) UIView *editingAccessoryView

Discussion

If the value of this property is not nil, the UITableViewCell class uses the given view for the accessory view in the table view’s editing state; it ignores the value of the editingAccessoryType property. The provided accessory view can be a framework-provided control or label or a custom view. The accessory view appears in the the right side of the cell.

The accessory type cross-fades between normal and editing states if it set for both states; use the accessoryType property to set the accessory view for the cell during the table view’s normal state. If this property is not set for both states, the cell is animated to slide or out, as necessary.

See Also

•   @property accessoryType
•   @property accessoryView
• – willTransitionToState:
• – didTransitionToState:

editingStyle

The editing style of the cell. (read-only)

@property(nonatomic, readonly) UITableViewCellEditingStyle editingStyle

Discussion

One of the constants described in “Cell Editing Style” is used as the value of this property; it specifies whether the cell is in an editable state and, if it is, whether it shows an insertion or deletion control. The default value is UITableViewCellEditingStyleNone (not editable). The delegate returns the value this property for a particular cell in its implementation of the tableView:editingStyleForRowAtIndexPath: method.

See Also

•   @property editing

font

The font of the title. (Deprecated. Instead, set the fonts of the UILabel objects assigned to the textLabel and detailTextLabel properties.)

@property(nonatomic, retain) UIFont *font

Discussion

If the value of this property is nil (the default), UITableViewCell uses a standard font optimized for the device.

hidesAccessoryWhenEditing

A Boolean value that determines whether the accessory view is hidden when the cell is being edited. (Deprecated. Use the editingAccessoryType and editingAccessoryView properties instead.)

@property(nonatomic) BOOL hidesAccessoryWhenEditing

Discussion

The default value is YES.

highlighted

A Boolean value that indicates whether the cell is highlighted.

@property(nonatomic, getter=isHighlighted) BOOL highlighted

Discussion

The highlighting affects the appearance of labels, image, and background. When the the highlighted state of a cell is set to YES, labels are drawn in their highlighted text color (default is white). The default value is is NO. If you set the highlighted state to YES through this property, the transition to the new state appearance is not animated. For animated highlighted-state transitions, see the setHighlighted:animated: method.

Note that for highlighting to work properly, you must fetch the cell’s labels using the textLabel and detailTextLabel properties and set each label’s highlightedTextColor property; for images, get the cell’s image using the imageView property and set the UIImageView object’s highlightedImage property.

image

The image to use as content for the cell. (Deprecated. Instead use the imageView property to get UIImageView object and then get or set the encapsulated image.)

@property(nonatomic, retain) UIImage *image

Discussion

The default value of the property is nil (no image). Images are positioned to the left of the title.

See Also

•   @property selectedImage

Related Sample Code

• TouchCells

imageView

Returns the image view of the table cell. (read-only)

@property(nonatomic, readonly, retain) UIImageView *imageView

Discussion

Returns the image view (UIImageView object) of the table view, which initially has no image set. If an image is set, it appears on the left side of the cell, before any label. UITableViewCell creates the image-view object when you create the cell.

See Also

• – initWithStyle:reuseIdentifier:

Related Sample Code

• PhotoLocations

indentationLevel

Adjusts the indentation level of a cell whose content is indented.

@property(nonatomic) NSInteger indentationLevel

Discussion

The default value of the property is zero (no indentation). The width for each level of indentation is determined by the indentationWidth property.

indentationWidth

The width for each level of indentation of a cell'€™s content.

@property(nonatomic) CGFloat indentationWidth

Discussion

The default indentation width is 10.0 points.

See Also

•   @property indentationLevel

lineBreakMode

The mode for for wrapping and truncating text in the cell. (Deprecated. Instead set the line-break mode attribute of the UILabel objects assigned to the textLabel and detailTextLabel properties.)

@property(nonatomic) UILineBreakMode lineBreakMode

Discussion

For further information, see the UILineBreakMode constants described in NSString UIKit Additions Reference. The default value is UILineBreakModeTailTruncation.

reuseIdentifier

A string used to identify a cell that is reusable. (read-only)

@property(nonatomic, readonly, copy) NSString *reuseIdentifier

Discussion

The reuse identifier is associated with a UITableViewCell object that the table-view’s delegate creates with the intent to reuse it as the basis (for performance reasons) for multiple rows of a table view. It is assigned to the cell object in initWithFrame:reuseIdentifier: and cannot be changed thereafter. A UITableView object maintains a queue (or list) of the currently reusable cells, each with its own reuse identifier, and makes them available to the delegate in the dequeueReusableCellWithIdentifier: method.

See Also

• – prepareForReuse

selected

A Boolean value that indicates whether the cell is selected.

@property(nonatomic, getter=isSelected) BOOL selected

Discussion

The selection affects the appearance of labels, image, and background. When the the selected state of a cell is set to YES, it draws the background for selected cells with its title in white. The default value is is NO. If you set the selection state to YES through this property, the transition to the new state appearance is not animated. For animated selected-state transitions, see the setSelected:animated: method.

See Also

•   @property selectionStyle

selectedBackgroundView

The view used as the background of the cell when it is selected.

@property(nonatomic, retain) UIView *selectedBackgroundView

Discussion

The default is nil for cells in plain-style tables (UITableViewStylePlain) and non-nil for section-group tables UITableViewStyleGrouped). UITableViewCell adds the value of this property as a subview only when the cell is selected. It adds the selected background view as a subview directly above the background view (backgroundView) if it is not nil, or behind all other views. Calling setSelected:animated: causes the selected background view to animate in and out with an alpha fade.

See Also

•   @property backgroundView

selectedImage

The image to use a cell content when the cell is selected. (Deprecated. Instead use the imageView property to obtain the UIImageView object and then get or set its highlightedImage property.)

@property(nonatomic, retain) UIImage *selectedImage

Discussion

The default value of this property is nil (no image).

See Also

•   @property image

selectedTextColor

The color of the title text when the cell is selected. (Deprecated. Instead set the selected text color attribute of the UILabel objects assigned to the textLabel and detailTextLabel properties.)

@property(nonatomic, retain) UIColor *selectedTextColor

Discussion

If the value of property is nil (the default), the color of text in a selected cell is white.

selectionStyle

The style of selection for a cell.

@property(nonatomic) UITableViewCellSelectionStyle selectionStyle

Discussion

The selection style is a backgroundView constant that determines the color of a cell when it is selected. The default value is UITableViewCellSelectionStyleBlue. See “Cell Selection Style” for a description of valid constants.

See Also

•   @property selected
• – setSelected:animated:

Related Sample Code

• AppPrefs
• BatteryStatus
• HeaderFooter
• LocateMe
• UICatalog

shouldIndentWhileEditing

A Boolean value that controls whether the cell background is indented when the table view is in editing mode.

@property(nonatomic) BOOL shouldIndentWhileEditing

Discussion

The default value is YES. This property is unrelated to indentationLevel. The delegate can override this value in tableView:shouldIndentWhileEditingRowAtIndexPath:. This property has an effect only on table views created in the grouped style (UITableViewStyleGrouped); it has no effect on UITableViewStylePlain table views.

showingDeleteConfirmation

Returns whether the cell is currently showing the delete-confirmation button. (read-only)

@property(nonatomic, readonly) BOOL showingDeleteConfirmation

Discussion

When users tap the deletion control (the red circle to the left of the cell), the cell displays a "Delete" button on the right side of the cell; this string is localized.

showsReorderControl

A Boolean value that determines whether the cell shows the reordering control.

@property(nonatomic) BOOL showsReorderControl

Discussion

The reordering control is gray, multiple horizontal bar control on the right side of the cell. Users can drag this control to reorder the cell within the table. The default value is NO. If the value is YES , the reordering control temporarily replaces any accessory view.

For the reordering control to appear, you must not only set this property but implement the UITableViewDataSource method tableView:moveRowAtIndexPath:toIndexPath:. In addition, if the data source implements tableView:canMoveRowAtIndexPath: to return NO, the reordering control does not appear in that designated row.

target

The target object to receive action messages. (Deprecated. Instead use the tableView:commitEditingStyle:forRowAtIndexPath: or tableView:accessoryButtonTappedForRowWithIndexPath: for handling taps on cells.)

@property(nonatomic, assign) id target

Discussion

The target object receives action messages when the user taps a cell'€™s insert button, delete button, or accessory view. The default value is nil, which tells the application to go up the responder chain to find a target. Note that the target is a weak reference.

See Also

•   @property editAction
•   @property accessoryAction

text

The text of the cell. (Deprecated. Use the textLabel and detailTextLabel properties instead.)

@property(nonatomic, copy) NSString *text

Discussion

The default is nil (no text).

Related Sample Code

• International Mountains

textAlignment

A constant that specifies the alignment of text in the cell. (Deprecated. Instead set the text alignment of the UILabel objects assigned to the textLabel and detailTextLabel properties.)

@property(nonatomic) UITextAlignment textAlignment

Discussion

If the value of the property is nil (the default), the title is left-aligned (UITextAlignmentLeft). See the descriptions of the UITextAlignment constants for alternative text alignments.

textColor

The color of the title text. (Deprecated. Instead set the text color attribute of the UILabel objects assigned to the textLabel and detailTextLabel properties.)

@property(nonatomic, retain) UIColor *textColor

Discussion

If the value of property is nil (the default), the color of text is black.

textLabel

Returns the label used for the main textual content of the table cell. (read-only)

@property(nonatomic, readonly, retain) UILabel *textLabel

Discussion

Holds the main label of the cell. UITableViewCell adds an appropriate label when you create the cell in a given cell style. See “Cell Styles” for descriptions of the main label in currently defined cell styles.

See Also

•   @property detailTextLabel
• – initWithStyle:reuseIdentifier:

Related Sample Code

• BatteryStatus
• BonjourWeb
• LocateMe
• UICatalog
• XMLPerformance

typedef enum {
   UITableViewCellStyleDefault,
   UITableViewCellStyleValue1,
   UITableViewCellStyleValue2,
   UITableViewCellStyleSubtitle
} UITableViewCellStyle;

typedef NSUInteger UITableViewCellStateMask;

enum {
   UITableViewCellStateDefaultMask                     = 0,
   UITableViewCellStateEditingMask                     = 1 << 0,
   UITableViewCellStateShowingDeleteConfirmationMask   = 1 << 1
};

typedef enum {
   UITableViewCellSelectionStyleNone,
   UITableViewCellSelectionStyleBlue,
   UITableViewCellSelectionStyleGray
} UITableViewCellSelectionStyle;

typedef enum {
   UITableViewCellEditingStyleNone,
   UITableViewCellEditingStyleDelete,
   UITableViewCellEditingStyleInsert
} UITableViewCellEditingStyle;

typedef enum {
   UITableViewCellAccessoryNone,
   UITableViewCellAccessoryDisclosureIndicator,
   UITableViewCellAccessoryDetailDisclosureButton,
   UITableViewCellAccessoryCheckmark
} UITableViewCellAccessoryType;

typedef enum {
   UITableViewCellSeparatorStyleNone,
   UITableViewCellSeparatorStyleSingleLine
} UITableViewCellSeparatorStyle;