To create a cell using one of the built-in cell styles, call initWithStyle:reuseIdentifier:. The reuseIdentifier is what allows cells previously assigned to rows that are now longer showing to be reused for cells that are; it will usually be the same for all cells in a table. Your choices of cell style are:

To experiment with the built-in cell styles, do this.

To get our table view into the interface, import "RootViewController.h" into AppDelegate.m, and add this line to AppDelegate’s application:didFinishLaunchingWithOptions::

self.window.rootViewController = [RootViewController new];

Now modify the RootViewController class (which comes with a lot of templated code), as in Example 21.1.

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
    return 1; ❶
}

- (NSInteger)tableView:(UITableView *)tableView
        numberOfRowsInSection:(NSInteger)section {
    return 20; ❷
}

- (UITableViewCell *)tableView:(UITableView *)tableView
         cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    static NSString *CellIdentifier = @"Cell";
    UITableViewCell *cell =
        [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
    if (cell == nil) {
        cell =
            [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault
                                   reuseIdentifier:CellIdentifier]; ❸
        ❹
    }
    cell.textLabel.text = @"Howdy there"; ❺
    return cell;
}

The idea is to start by generating a single cell in a built-in cell style and then to examine and experiment with its appearance by tweaking the code and running the app. The key parts of the code are:

Build and run the app. Behold your table. Now you can start experimenting.

The flexibility of the built-in styles is based mostly on the flexibility of UILabels. Not everything can be customized, because after you return the cell some further configuration takes place, which may override your settings. For example, the size and position of the cell’s subviews are not up to you. (I’ll explain how to get around that, a little later.) But you get a remarkable degree of freedom. Here are some basic UILabel properties for you to play with (and I’ll talk much more about UILabels in Chapter 23):

The image view’s frame can’t be changed, but you can inset its apparent size by supplying a smaller image and setting the image view’s contentMode to UIViewContentModeCenter. It’s probably a good idea in any case, for performance reasons, to supply images at their drawn size and resolution rather than making the drawing system scale them for you (see the last section of Chapter 20). For example:

UIImage* im = [UIImage imageNamed:@"pic.png"];
UIGraphicsBeginImageContextWithOptions(CGSizeMake(36,36), YES, 0);
[im drawInRect:CGRectMake(0,0,36,36)];
UIImage* im2 = UIGraphicsGetImageFromCurrentImageContext();
UIGraphicsEndImageContext();
cell.imageView.image = im2;
cell.imageView.contentMode = UIViewContentModeCenter;

The cell itself also has some properties you can play with:

Applying a backgroundView or a backgroundColor can be tricky, because:

In this example, we set the backgroundView to display an image with some transparency at the outside edges, so that the backgroundColor shows behind it. We set the selectedBackgroundView to an almost transparent dark rectangle, to darken that image when the cell is selected. And we give the textLabel a clear background color so that the rest of our work shows through (Figure 21.3):

UIImageView* v = [UIImageView new];
v.contentMode = UIViewContentModeScaleToFill;
v.image = [UIImage imageNamed:@"linen.png"];
cell.backgroundView = v;
UIView* v2 = [UIView new];
v2.backgroundColor = [UIColor colorWithWhite:0.2 alpha:0.1];
cell.selectedBackgroundView = v2;
cell.textLabel.backgroundColor = [UIColor clearColor];

I’d put that code in the spot numbered 4 in Example 21.1. These features are to be true of every cell ever displayed in the table, and they need to be configured just once for every cell as it first comes into existence. There’s no need to waste time doing the same thing all over again when an existing cell is reused.

Figure 21.3. A cell with an image background

Finally, there are a few properties of the table view itself worth playing with:

iOS 6 introduces a new way of obtaining a cell in tableView:cellForRowAtIndexPath:. Instead of calling dequeueReusableCellWithIdentifier: to obtain the cell, you call dequeueReusableCellWithIdentifier:forIndexPath:, passing along as the second argument the same indexPath: value that you already received. As far as I can tell, however, the indexPath: parameter does nothing whatever, except to distinguish the two methods from one another!

The reason for calling this new method is twofold:

This is a very elegant mechanism, but it raises some questions:

Here’s a complete example, also illustrating heavy customization of a table view cell’s background and apparent shape. It’s a UITableViewCellStyleValue2 cell (Figure 21.4), and I register a UITableViewCell subclass (MyCell) in order to get it. I draw the cell’s background view as a gray gradient, using its layer properties (Chapter 16) to give it a border with rounded corners. My GradientView class is just a UIView whose layerClass is CAGradientLayer, and because MyCell and GradientView are so minimal, and are used only by RootViewController, I’ve put them into the RootViewController implementation file:

@interface MyCell:UITableViewCell
@end
@implementation MyCell
-(id)initWithStyle:(UITableViewCellStyle)style
   reuseIdentifier:(NSString *)reuseIdentifier {
    self = [super initWithStyle:UITableViewCellStyleValue2
                reuseIdentifier:reuseIdentifier];
    return self;
}
@end

@interface GradientView:UIView
@end
@implementation GradientView
+(Class)layerClass { return [CAGradientLayer class]; }
@end

@implementation RootViewController
-(void)viewDidLoad {
    [super viewDidLoad];
    [self.tableView registerClass:[MyCell class]
           forCellReuseIdentifier:@"Cell"];
}

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
    return 1;
}

- (NSInteger)tableView:(UITableView *)tableView
        numberOfRowsInSection:(NSInteger)section {
    return 20;
}

- (UITableViewCell *)tableView:(UITableView *)tableView
        cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    UITableViewCell *cell =
        [tableView dequeueReusableCellWithIdentifier:@"Cell"
                                        forIndexPath:indexPath];
    if (cell.backgroundView == nil) { // do one-time configurations
        UIView* v = [UIView new];
        v.backgroundColor = [UIColor blackColor];
        UIView* v2 = [GradientView new];
        CAGradientLayer* lay = (CAGradientLayer*)v2.layer;
        lay.colors = @[(id)[UIColor colorWithWhite:0.6 alpha:1].CGColor,
        (id)([UIColor colorWithWhite:0.4 alpha:1].CGColor)];
        lay.borderWidth = 1;
        lay.borderColor = [UIColor blackColor].CGColor;
        lay.cornerRadius = 5;
        [v addSubview:v2];

        v2.autoresizingMask = UIViewAutoresizingFlexibleHeight |
                              UIViewAutoresizingFlexibleWidth;
        cell.backgroundView = v;
        cell.textLabel.font = [UIFont fontWithName:@"Helvetica-Bold" size:16];
        cell.textLabel.textColor = [UIColor whiteColor];
        cell.textLabel.backgroundColor = [UIColor clearColor];
        cell.detailTextLabel.backgroundColor = [UIColor clearColor];
    }
    cell.textLabel.text = @"Text label";
    cell.detailTextLabel.text = @"Detail text label";
    return cell;
}
@end

Figure 21.4. A cell with a custom gradient background

I’m going to adopt dequeueReusableCellWithIdentifier:forIndexPath: from here on. It isn’t backwards-compatible with iOS 5 and before, but it’s a great new feature. Also, it’s consistent with other ways of generating custom cells, as I’ll explain in the next section.

The built-in cell styles give the beginner a leg up in getting started with table views, but there is nothing sacred about them, and sooner or later you’ll probably want to go beyond them and put yourself in charge of how a table’s cells look and what subviews they contain. There are four possible approaches:

I’ll illustrate each approach.

Overriding a cell’s subview layout

You can’t directly change the frame of a built-in cell style subview in tableView:cellForRowAtIndexPath: or tableView:willDisplayCell:forRowAtIndexPath:, because after your changes, the cell’s layoutSubviews comes along and overrides them. The workaround is to override the cell’s layoutSubviews! This is a straightforward solution if your main objection to a built-in style is the frame of an existing subview.

To illustrate, let’s modify a UITableViewCellStyleDefault cell so that the image is at the right end instead of the left end (Figure 21.5). We’ll make a UITableViewCell subclass, MyCell, remembering to register MyCell with the table view, so that dequeueReusableCellWithIdentifier:forIndexPath: produces a MyCell instance; here is MyCell’s layoutSubviews:

- (void) layoutSubviews {
    [super layoutSubviews];
    CGRect cvb = self.contentView.bounds;
    CGRect imf = self.imageView.frame;
    imf.origin.x = cvb.size.width - imf.size.width;
    self.imageView.frame = imf;
    CGRect tf = self.textLabel.frame;
    tf.origin.x = 5;
    self.textLabel.frame = tf;
}

Figure 21.5. A cell with its label and image view swapped

In using this technique, I find it easier to move the subviews using their frame, rather than with constraints. Otherwise, the runtime (which still thinks it owns these subviews) tries to fight us.

- (UITableViewCell *)tableView:(UITableView *)tableView
        cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    UITableViewCell *cell =
        [tableView dequeueReusableCellWithIdentifier:@"Cell"
                                        forIndexPath:indexPath];
    if (cell.backgroundView == nil) {
        // ... add background view as before ...
        //  now insert our own views into the contentView
        UIImageView* iv = [UIImageView new];
        iv.tag = 1;
        [cell.contentView addSubview:iv];
        UILabel* lab = [UILabel new];
        lab.tag = 2;
        [cell.contentView addSubview:lab];
        // we can use autolayout to lay them out
        NSDictionary* d = NSDictionaryOfVariableBindings(iv, lab);
        iv.translatesAutoresizingMaskIntoConstraints = NO;
        lab.translatesAutoresizingMaskIntoConstraints = NO;
        // image view is vertically centered
        [cell.contentView addConstraint:
         [NSLayoutConstraint
          constraintWithItem:iv attribute:NSLayoutAttributeCenterY
          relatedBy:0
          toItem:cell.contentView attribute:NSLayoutAttributeCenterY
          multiplier:1 constant:0]];
        // it's a square
        [cell.contentView addConstraint:
         [NSLayoutConstraint
          constraintWithItem:iv attribute:NSLayoutAttributeWidth
          relatedBy:0
          toItem:iv attribute:NSLayoutAttributeHeight
          multiplier:1 constant:0]];
        // label has height pinned to superview
        [cell.contentView addConstraints:
         [NSLayoutConstraint
          constraintsWithVisualFormat:@"V:|[lab]|"
          options:0 metrics:nil views:d]];
        // horizontal margins
        [cell.contentView addConstraints:
         [NSLayoutConstraint
          constraintsWithVisualFormat:@"H:|-5-[lab]-10-[iv]-5-|"
          options:0 metrics:nil views:d]];
    }
    UILabel* lab = (UILabel*)[cell viewWithTag: 2];
    // ... set up lab here ...
    UIImageView* iv = (UIImageView*)[cell viewWithTag: 1];
    // ... set up iv here ...
    return cell;
}

UILabel* lab = (UILabel*)[cell viewWithTag: 2];
// ... set up lab here ...
UIImageView* iv = (UIImageView*)[cell viewWithTag: 1];
// ... set up iv here ...
return cell;

[self.tableView registerNib:[UINib nibWithNibName:@"MyCell" bundle:nil]
     forCellReuseIdentifier:@"Cell"];

MyCell* theCell = (MyCell*)cell;
UILabel* lab = theCell.theLabel;
// ... set up lab here ...
UIImageView* iv = theCell.theImageView;
// ... set up iv here ...
return cell;

@interface GradientView:UIView
@end
@implementation GradientView
+(Class)layerClass { return [CAGradientLayer class]; }
@end

@implementation MyGradientBackView
- (void) awakeFromNib {
    [super awakeFromNib];
    self.backgroundColor = [UIColor blackColor];
    UIView* v2 = [GradientView new];
    CAGradientLayer* lay = (CAGradientLayer*)v2.layer;
    lay.colors = @[(id)[UIColor colorWithWhite:0.6 alpha:1].CGColor,
    (id)([UIColor colorWithWhite:0.4 alpha:1].CGColor)];
    lay.borderWidth = 1;
    lay.borderColor = [UIColor blackColor].CGColor;
    lay.cornerRadius = 5;
    [self addSubview:v2];
    v2.frame = self.bounds;
    v2.autoresizingMask = UIViewAutoresizingFlexibleHeight |
                          UIViewAutoresizingFlexibleWidth;
}
@end

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
    return 1;
}
- (NSInteger)tableView:(UITableView *)tableView
        numberOfRowsInSection:(NSInteger)section {
    return 20;
}
- (UITableViewCell *)tableView:(UITableView *)tableView
         cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    MyCell *cell =
        (MyCell*)[tableView dequeueReusableCellWithIdentifier:@"Cell"
                                                 forIndexPath:indexPath];
    cell.theLabel.text =
        @"The author of this book, who would rather be out dirt biking";
    UIImage* im = [UIImage imageNamed:@"moi.png"];
    UIGraphicsBeginImageContextWithOptions(CGSizeMake(36,36), YES, 0.0);
    [im drawInRect:CGRectMake(0,0,36,36)];
    UIImage* im2 = UIGraphicsGetImageFromCurrentImageContext();
    UIGraphicsEndImageContext();
    cell.theImageView.image = im2;
    return cell;
}

Like Katherine Hepburn in Pat and Mike, the basis of your success (as a data source) is your ability, at any time, to answer the Three Big Questions. The questions the table view will ask you are a little different from the questions Mike asks Pat, but the principle is the same: know the answers, and be able to recite them at any moment. Here they are:

I have nothing particular to say about precisely how you’re going to fulfill these obligations. It all depends on your data model and what your table is trying to portray. The important thing is to remember that you’re going to be receiving an NSIndexPath specifying a section and a row, and you need to be able to lay your hands on the data corresponding to that slot now and configure the cell now. So construct your model, and your algorithm for consulting it in the Three Big Questions, accordingly.

For example, suppose our table is to list the names of the Pep Boys. Our data model might be an NSArray of string names. Our table has only one section. So our code might look like this:

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
    if (!pep) // data not ready?
        return 0;
    return 1;
}
- (NSInteger)tableView:(UITableView *)tableView
        numberOfRowsInSection:(NSInteger)section {
    return [self.pep count];
}
- (UITableViewCell *)tableView:(UITableView *)tableView
         cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    MyCell *cell =
        (MyCell*)[tableView dequeueReusableCellWithIdentifier:@"Cell"
                                                 forIndexPath:indexPath];
    cell.theLabel.text = (self.pep)[indexPath.row];
    return cell;
}

At this point you may be feeling some exasperation. You want to object: “But that’s trivial!” Exactly so! Your access to the data model should be trivial. That’s the sign of a data model that’s well designed for access by your table view’s data source. Your implementation of tableView:cellForRowAtIndexPath: might have some interesting work to do in order to configure the form of the cell, but accessing the actual data should be simple and boring.

For example, consider Figure 19.1. The actual code that fetches the data is trivial:

FPItem* item = self.parsedData.items[indexPath.row];
NSString* title = item.title;
NSString* blurb = item.blurbOfItem;

That’s all there is to it. And the reason why that’s all there is to it is that I’ve structured the data model to be ready for access in exactly this way. However, there then follow about thirty lines of code formatting the layout of the text within the cell. The format is elaborate; accessing the data is not.

Another important aspect of tableView:cellForRowAtIndexPath: is that, as I’ve already illustrated, your strategy will probably be to keep memory usage at a minimum by reusing cells. Once a cell is no longer visible on the screen, it can be slotted into a row that is visible — with its portrayed data appropriately modified, of course! — so that no more than the number of simultaneously visible cells need to exist at any given moment. A table view is ready to implement this strategy for you; all you have to do is call dequeueReusableCellWithIdentifier:forIndexPath:. For any given identifier, you’ll be handed either a newly minted cell or a reused cell that previously appeared in the table view but is now no longer needed because it has scrolled out of view. The table view can maintain more than one cache of reusable cells; this could be useful if your table view contains more than one type of cell (where the meaning of the concept “type of cell” is pretty much up to you). This why you must name each cache, by attaching an identifier string to any cell that can be reused. All the examples in this chapter (and in this book, and in fact in every UITableView I’ve ever created) use just one cache and just one identifier.

To prove to yourself the efficiency of the cell-caching architecture, do something to differentiate newly instantiated cells from reused cells, and count the newly instantiated cells, like this:

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
    return 1;
}

- (NSInteger)tableView:(UITableView *)tableView
        numberOfRowsInSection:(NSInteger)section {
    return 100;
}

- (UITableViewCell *)tableView:(UITableView *)tableView
         cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    MyCell* cell =
        (MyCell*)[tableView dequeueReusableCellWithIdentifier:@"Cell"
                                                 forIndexPath:indexPath];
    if (!cell.backgroundView) {
        cell.backgroundView = [UIView new]
        NSLog(@"creating a new cell");
    }
    UILabel* lab = cell.theLabel;
    lab.text = [NSString stringWithFormat:@"This is row %i of section %i",
                indexPath.row, indexPath.section];
    return cell;
}

When we run this code and scroll through the table, every cell is numbered correctly, so there appear to be 100 cells. But the log messages show us that only 11 distinct cells are ever actually created.

If your tableView:cellForRowAtIndexPath: code configures the form of newly instantiated cells once (stage 4 in Example 21.1), you have to distinguish whether this cell is a newly instantiated cell; the whole idea is to avoid reconfiguring a reused cell. But when you provide a cell’s final individual configuration (stage 5 in Example 21.1), you do not know or care whether the cell is new or reused. Therefore, you should always configure everything about the cell that might need configuring. If you fail to do this, and if the cell is reused, you might be surprised when some aspect of the cell is left over from its previous use; similarly, if you fail to do this, and if the cell is new, you might be surprised when some aspect of the cell isn’t configured at all.

For example, in one of my apps that lists article titles in a table, there is a little loudspeaker icon that should appear in the cell only if there is a recording associated with this article. So I initially wrote this code:

if (item.enclosures && [item.enclosures count])
    cell.speaker.hidden = NO;

This turned out to be a mistake, because when a cell was reused, it had a visible loudspeaker icon if, in a previous incarnation, it had ever had a visible loudspeaker icon. The solution was to rewrite the logic to cover all possibilities, like this:

cell.speaker.hidden = !(item.enclosures && [item.enclosures count]);

You do get a sort of second bite of the cherry: there’s a delegate method, tableView:willDisplayCell:forRowAtIndexPath:, that is called for every cell just before it appears in the table. This is absolutely the last minute to configure a cell. But don’t misuse this method. You’re functioning as the delegate here, not the data source; you may set the final details of the cell’s appearance — as I mentioned earlier, this is a good place to set a cell’s background color if you don’t want it to come from the table’s background color — but you shouldn’t be consulting the data model at this point.

New in iOS 6 is an additional delegate method, tableView:didEndDisplayingCell:forRowAtIndexPath:. This tells you that the cell no longer appears in the interface and has become free for reuse. You could take advantage of this to tear down any resource-heavy customization of the cell (I’ll give an example in Chapter 37), or simply to prepare it somehow for subsequent reuse. (A UITableViewCell has a prepareForReuse method, but you’d need a subclass to override it, and in any case it arrives when the cell is about to be reused, whereas tableView:didEndDisplayingCell:forRowAtIndexPath: arrives much earlier, as soon as the cell is no longer being used.)

Your table data can be expressed as divided into sections. You might clump your data into sections for various reasons (and doubtless there are other reasons beyond these):

The number of sections is determined by your reply to numberOfSectionsInTableView:. For each section, the table view will consult your data source and delegate to learn whether this section has a header or a footer, or both, or neither (the default).

The UITableViewHeaderFooterView class, new in iOS 6, is a UIView subclass intended specifically for use as the view of a header or footer; much like a table cell, it is reusable. It has the following properties:

You can supply a header or footer in two ways:

In addition, two pairs of delegate methods permit you to perform final configurations on your header or footer views:

Some lovely effects can be created by modifying a header or footer view, especially because they are further forward than the table cells. For example, a header with transparency shows the table cells as they scroll behind it; a header with a shadow casts that shadow on the adjacent table cell.

A table that is to have section headers or footers (or both) may require some advance planning in the formation of its data model. Just as with a table cell, a section title must be readily available so that it can be supplied quickly in real time. A structure that I commonly use is a pair of parallel arrays: an array of strings containing the section names, and an array of subarrays containing the data for each section.

For example, suppose we intend to display the names of all 50 US states in alphabetical order as the rows of a table view, and that we wish to divide the table into sections according to the first letter of each state’s name. I’ll prepare the data model by walking through the list of state names, creating a new section name and a new subarray when I encounter a new first letter:

NSString* s =
    [NSString stringWithContentsOfFile:
        [[NSBundle mainBundle] pathForResource:@"states" ofType:@"txt"]
                                      encoding:NSUTF8StringEncoding error:nil];
NSArray* states = [s componentsSeparatedByString:@"\n"];
self.sectionNames = [NSMutableArray array];
self.sectionData = [NSMutableArray array];
NSString* previous = @"";
for (NSString* aState in states) {
    // get the first letter
    NSString* c = [aState substringToIndex:1];
    // only add a letter to sectionNames when it's a different letter
    if (![c isEqualToString: previous]) {
        previous = c;
        [self.sectionNames addObject: [c uppercaseString]];
        // and in that case, also add a new subarray to our array of subarrays
        NSMutableArray* oneSection = [NSMutableArray array];
        [self.sectionData addObject: oneSection];
    }
    [[self.sectionData lastObject] addObject: aState];
}

The value of this preparatory dance is evident when we are bombarded with questions from the table view about cells and headers; supplying the answers is trivial:

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
    return [self.sectionNames count];
}

- (NSInteger)tableView:(UITableView *)tableView
        numberOfRowsInSection:(NSInteger)section {
    return [(self.sectionData)[section] count];
}

- (UITableViewCell *)tableView:(UITableView *)tableView
         cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    UITableViewCell *cell =
        [tableView dequeueReusableCellWithIdentifier:@"Cell"
                                        forIndexPath:indexPath];
    NSString* s = self.sectionData[indexPath.section][indexPath.row];
    cell.textLabel.text = s;
    return cell;
}

- (NSString *)tableView:(UITableView *)tableView
        titleForHeaderInSection:(NSInteger)section {
    return self.sectionNames[section];
}

Let’s modify that example to illustrate customization of a header view. I’ve already registered my header identifier in viewDidLoad:

[self.tableView registerClass:[UITableViewHeaderFooterView class]
     forHeaderFooterViewReuseIdentifier:@"Header"];

Now, instead of tableView:titleForHeaderInSection:, I’ll implement tableView:viewForHeaderInSection:. For completely new views, I’ll place my own label and an image view inside the contentView and give them their basic configuration; then I’ll perform individual configuration on all views, new or reused, very much like tableView:cellForRowAtIndexPath::

- (UIView *)tableView:(UITableView *)tableView
        viewForHeaderInSection:(NSInteger)section {
    UITableViewHeaderFooterView* h =
        [tableView dequeueReusableHeaderFooterViewWithIdentifier:@"Header"];
    if (![h.tintColor isEqual: [UIColor redColor]]) {
        h.tintColor = [UIColor redColor];
        UILabel* lab = [UILabel new];
        lab.tag = 1;
        lab.font = [UIFont fontWithName:@"Georgia-Bold" size:22];
        lab.textColor = [UIColor greenColor];
        lab.backgroundColor = [UIColor clearColor];
        [h.contentView addSubview:lab];
        UIImageView* v = [UIImageView new];
        v.tag = 2;
        v.backgroundColor = [UIColor blackColor];
        v.image = [UIImage imageNamed:@"us_flag_small.gif"];
        [h.contentView addSubview:v];
        lab.translatesAutoresizingMaskIntoConstraints = NO;
        v.translatesAutoresizingMaskIntoConstraints = NO;
        [h.contentView addConstraints:
         [NSLayoutConstraint
          constraintsWithVisualFormat:@"H:|-5-[lab(25)]-10-[v(40)]"
          options:0 metrics:nil views:@{@"v":v, @"lab":lab}]];
        [h.contentView addConstraints:
         [NSLayoutConstraint
          constraintsWithVisualFormat:@"V:|[v]|"
           options:0 metrics:nil views:@{@"v":v}]];
        [h.contentView addConstraints:
         [NSLayoutConstraint
          constraintsWithVisualFormat:@"V:|[lab]|"
           options:0 metrics:nil views:@{@"lab":lab}]];
    }
    UILabel* lab = (UILabel*)[h.contentView viewWithTag:1];
    lab.text = self.sectionNames[section];
    return h;
}

If your table view has the plain style, you can add an index down the right side of the table, which the user can tap to jump to the start of a section — helpful for navigating long tables. To generate the index, implement the data source method sectionIndexTitlesForTableView:, returning an NSArray of string titles to appear as entries in the index. This works even if there are no section headers. The index will appear only if the number of rows exceeds the table view’s sectionIndexMinimumDisplayRowCount property value; the default is 0 (not NSIntegerMax as claimed by the documentation), so the index is always displayed by default. You will want the index entries to be short — preferably just one character — because they will be partially obscuring the right edge of the table; plus, each cell’s content view will shrink to compensate, so you’re sacrificing some cell real estate.

For our list of state names, that’s trivial, as it should be:

- (NSArray *)sectionIndexTitlesForTableView:(UITableView *)tableView {
    return self.sectionNames;
}

Before iOS 6, there was no official way to modify the index’s appearance (such as the color of its entries). New in iOS 6, you can set the table view’s sectionIndexColor and sectionIndexTrackingBackgroundColor (the color that appears behind the index while the user’s finger is sliding over it).

Normally, there will be a one-to-one correspondence between the index entries and the sections; when the user taps an index entry, the table jumps to the start of the corresponding section. However, under certain circumstances you may want to customize this correspondence. For example, suppose there are 40 sections, but there isn’t room to display 40 index entries comfortably on the iPhone. The index will automatically curtail itself, omitting some index entries and inserting bullets to suggest the omission, but you might prefer to take charge of the situation by supplying a shorter index. In such a case, implement the data source method tableView:sectionForSectionIndexTitle:atIndex:, returning the index of the section to jump to for this section index. Both the section index title and its index are passed in, so you can use whichever is convenient.

Apple’s documentation elaborates heavily on the details of implementing the model behind a table with an index and suggests that you rely on a class called UILocalizedIndexedCollation. This class is effectively a way of generating an ordered list of letters of the alphabet, with methods for helping to sort an array of strings and separate it into sections. This might be useful if you need your app to be localized, because the notion of the alphabet and its order changes automatically depending on the user’s preferred language. But this notion is also fixed; you can’t readily use a UILocalizedIndexCollation to implement your own sort order. For example, UILocalizedIndexCollation was of no use to me in writing my Greek and Latin vocabulary apps, in which the Greek words must be sorted, sectioned, and indexed according to the Greek alphabet, and the Latin words use a reduced version of the English alphabet (no initial J, K, or V through Z). Thus I’ve never actually bothered to use UILocalizedIndexedCollation.

The table view has no direct connection to the underlying data. If you want the table view display to change because the underlying data have changed, you have to cause the table view to refresh itself; basically, you’re requesting that the Three Big Questions be asked all over again. At first blush, this seems inefficient (“regenerate all the data??”); but it isn’t. Remember, in a table that caches reusable cells, there are no cells of interest other than those actually showing in the table at this moment. Thus, having worked out the layout of the table through the section header and footer heights and row heights, the table has to regenerate only those cells that are actually visible.

You can cause the table data to be refreshed using any of several methods:

The second two methods can perform animations that cue the user as to what’s changing. The withRowAnimation: parameter is one of the following:

If all you need to do is to refresh the index, call reloadSectionIndexTitles; this calls the data source’s sectionIndexTitlesForTableView:.

It is also possible to access and alter a table’s individual cells directly. This can be a far more lightweight approach to refreshing the table, plus you can supply your own animation within the cell as it alters its appearance. To do this, you need direct access to the cell you want to change. You’ll probably want to make sure the cell is visible within the table view’s bounds; if you’re taking proper advantage of the table’s reusable cell caching mechanism, nonvisible cells don’t really exist (except as potential cells waiting in the reuse cache), and there’s no point changing them, as they’ll be changed when they are scrolled into view, through the usual call to tableView:cellForRowAtIndexPath:. Here are some UITableView methods that mediate between cells, rows, and visibility:

It is important to bear in mind that the cells are not the data (view is not model). If you change the content of a cell manually, make sure that you have also changed the model corresponding to it, so that the row will appear correctly if its data is reloaded later.

By the same token, you can get access to the views constituting headers and footers, by calling headerViewForSection: or footerViewForSection: (new in iOS 6). Thus you could modify a view directly. There is no method for learning what header or footer views are visible, but you should assume that if a section is returned by indexPathsForVisibleRows, its header or footer might be visible.

iOS 6 introduces a new standard interface object for allowing the user to ask that a table view be refreshed — the UIRefreshControl. It is located at the top of the table view (above the table header view, if there is one), and is normally offscreen. To request a refresh, the user scrolls the table view downward to reveal the refresh control and holds there long enough to indicate that this scrolling is deliberate. The refresh control then acknowledges visually that it is refreshing, and remains visible until refreshing is complete. (This interface architecture, known as pull to refresh, was invented by Loren Brichter for the Twitter app and has become widespread in various clever implementations; with the UIRefreshControl, Apple is imitating and sanctioning this interface for the first time.)

Oddly, a UIRefreshControl is a property, not of a table view, but of a UITableViewController (its refreshControl). It is a control (UIControl, Chapter 25), so it has an action message, emitted for its UIControlEventValueChanged. You can give a table view controller a refresh control in the nib editor, but hooking up its action doesn’t work, so you have to do it in code:

-(void)viewDidLoad {
    [super viewDidLoad];
    [self.refreshControl addTarget:self action:@selector(doRefresh:)
                  forControlEvents:UIControlEventValueChanged];
}

Once a refresh control’s action message has fired, the control remains visible and indicates by animation (similar to an activity indicator) that it is refreshing until you send it the endRefreshing message. You can initiate a refresh animation in code with beginRefreshing, but this does not fire the action message or display the refresh control; to display it, scroll the table view:

[self.tableView setContentOffset:CGPointMake(0,-44) animated:YES];
[self.refreshControl beginRefreshing];
// ... now actually do refresh, and later send endRefreshing

A refresh control also has a tintColor and an attributedString, which is displayed as a label below the activity indicator (on attributed strings, see Chapter 23). I use a refresh control and take advantage of its attributed string in the current version of the TidBITS News app to tell the user when the table was last refreshed (and then I scroll the table view just enough to reveal the label):

NSString* s = [df stringFromDate: [NSDate date]]; // df is an NSDateFormatter
self.refreshControl.attributedTitle =
    [[NSAttributedString alloc] initWithString:s
        attributes: @{NSForegroundColorAttributeName:[UIColor whiteColor]}];
[self.tableView setContentOffset:CGPointMake(0,-21) animated:YES];

Most tables have rows that are all the same height, as set by the table view’s rowHeight. However, the delegate’s tableView:heightForRowAtIndexPath: can be used to make different rows different heights. You can see this in the TidBITS News app; look at Figure 19.1, where the first cell is shorter than the second cell (because the headline is one line instead of two).

Here are some things to remember when implementing a table whose rows can have different heights:

This can be a little tricky, because you have to figure out how much room your interface objects will occupy given the contents they’ll actually have when they appear in the table. For example, I face this problem in my Albumen app, in a table where each cell displays a song’s title (in a label) and the song’s artist (in another label). These labels will be displayed one above the other; I want each of them to be just tall enough to contain its content, and the cell to be just tall enough to contain the labels plus some reasonable spacing. What we need is a way to ask a UILabel, “How tall would you be if you contained this text?”

Fortunately there’s a way to do that — two ways, actually. We could send a UILabel the sizeThatFits: message, handing it a size that represents its actual maximum width and an excessively tall height. Equivalently, we could send the label’s string the sizeWithFont:constrainedToSize: message; this works because we are guaranteed that a UILabel will draw its text the same way that text would draw itself. It happens that I use the latter method.

I start with a utility method, labelHeightsForRow:, that calculates the heights of both labels given their text and font. Note that this method must be able to consult the data model, to learn what the text will be for each label, and it must know in advance the width and font of each label:

- (NSArray*) labelHeightsForRow: (NSInteger) row {
    NSString* title = (self.titles)[row];
    NSString* artist = (self.artists)[row];
    // values used in next two lines have been cached as ivars at load time
    CGSize tsz = [title sizeWithFont:self.titleFont
                  constrainedToSize:CGSizeMake(_tw, 4000)];
    CGSize asz = [artist sizeWithFont:self.artistFont
                  constrainedToSize:CGSizeMake(_aw, 4000)];
    return @[@(tsz.height), @(asz.height)];
}

My tableView:heightForRowAtIndexPath: implementation can then call labelHeightsForRow:, using those heights, along with some #defined spacer values, to work out the total height of any requested cell:

- (CGFloat)tableView:(UITableView *)tableView
        heightForRowAtIndexPath:(NSIndexPath *)indexPath {
    NSArray* arr = [self labelHeightsForRow: indexPath.row];
    return ([arr[0] floatValue] + [arr[1] floatValue] +
            _topspace + _midspace + _thirdrow + _midspace + _bottomspace);
}

My tableView:willDisplayCell:forRowAtIndexPath: implementation calls labelHeightsForRow: again, using those same calculated heights again and the same #defined spacer values again; the difference is that this time it actually lays out all the subviews of the content view:

- (void) tableView:(UITableView *)tableView
        willDisplayCell:(UITableViewCell *)cell
        forRowAtIndexPath:(NSIndexPath *)indexPath {
    // work out heights of views 1 and 2, origin.y of views 1, 2, 3, 4
    CGRect f = cell.frame;
    f.size.height =
        [self tableView: tableView heightForRowAtIndexPath: indexPath];
    cell.frame = f;
    NSArray* arr = [self labelHeightsForRow: indexPath.row];
    //
    CGRect f1 = [cell viewWithTag: 1].frame;
    f1.size.height = [arr[0] floatValue];
    f1.origin.y = _topspace;
    [cell viewWithTag: 1].frame = f1;
    //
    CGRect f2 = [cell viewWithTag: 2].frame;
    f2.size.height = [arr[1] floatValue];
    f2.origin.y = f1.origin.y + f1.size.height + _midspace;
    [cell viewWithTag: 2].frame = f2;
    // ... and so on ...
}

This works, but there’s something depressing about all that painstakingly calculated layout. When autolayout and constraints came along, I was filled with hope. Instead of calculating the heights myself, surely I could fill a cell with its actual values and let the autolayout system work out the cell’s height based on its internal constraints. The key method here is systemLayoutSizeFittingSize:; sent to a view, it tells the view to adopt the given size, to the extent that its internal constraints will allow.

So here’s my new strategy. I have a new utility method setUpCell:forIndexPath: that assigns all labels in my cell their actual values for the given row. I know that tableView:heightForRowAtIndexPath: will be called first, so the first time it’s called, I call my utility method for all the cells in the table. For each cell, I thus populate the labels; I then use autolayout to get the height of each resulting cell; and I store those heights in an array, from which I can instantly draw the answer to all subsequent calls to tableView:heightForRowAtIndexPath::

- (CGFloat)tableView:(UITableView *)tableView
        heightForRowAtIndexPath:(NSIndexPath *)indexPath {
    if (!self.heights) {
        // first time! determine all heights once for all
        NSMutableArray* marr = [NSMutableArray array];
        NSArray* objects = [[UINib nibWithNibName:@"TrackCell" bundle:nil]
                            instantiateWithOwner:nil options:nil];
        UITableViewCell* cell = objects[0];
        NSInteger u = [self.titles count];
        for (NSInteger i = 0; i < u; i++) {
            [self setUpCell:cell forIndexPath:
                [NSIndexPath indexPathForRow:i inSection:0]];
            CGSize sz = [cell
                systemLayoutSizeFittingSize:UILayoutFittingCompressedSize];
            [marr addObject: @(sz.height)];
        };
        self.heights = marr;
    }
    return [self.heights[indexPath.row] floatValue];
}

In tableView:cellForRowAtIndexPath:, I call setUpCell:forIndexPath: again, secure in the knowledge that the cell height, the label contents, and the constraints will work exactly the same way as before. This is far more satisfying, but unfortunately the use of systemLayoutSizeFittingSize: makes this approach noticeably slower than the old manual layout way.

Deletion of table items is the default, so there’s not much for us to do in order to implement it. If our view controller is a UITableViewController and we’ve displayed the Edit button as its navigation item’s right button, everything happens automatically: the user taps the Edit button, the view controller’s setEditing:animated: is called, the table view’s setEditing:animated: is called, and the cells all show the minus button at the left end. The user can then tap a minus button; a Delete button appears at the cell’s right end. You can customize the Delete button’s title with the table delegate method tableView:titleForDeleteConfirmationButtonForRowAtIndexPath:.

What is not automatic is the actual response to the Delete button. For that, we need to implement tableView:commitEditingStyle:forRowAtIndexPath:. Typically, you’ll remove the corresponding entry from the underlying model data, and you’ll call deleteRowsAtIndexPaths:withRowAnimation: or deleteSections:withRowAnimation: to update the appearance of the table. As I said a moment ago, you must delete the row or section in such a way as to keep the table display coordinated with the model’s structure. Otherwise, the app may crash (with an extremely helpful error message).

To illustrate, let’s suppose once again that the underlying model is a pair of parallel arrays, an array of strings (sectionNames) and an array of arrays (sectionData). These arrays must now be mutable. Our approach will be in two stages:

- (void)tableView:(UITableView *)tableView
        commitEditingStyle:(UITableViewCellEditingStyle)editingStyle
         forRowAtIndexPath:(NSIndexPath *)ip {
    [self.sectionData[ip.section] removeObjectAtIndex:ip.row];
    if ([self.sectionData[ip.section] count] == 0) {
        [self.sectionData removeObjectAtIndex: ip.section];
        [self.sectionNames removeObjectAtIndex: ip.section];
        [tableView deleteSections:[NSIndexSet indexSetWithIndex: ip.section]
                 withRowAnimation:UITableViewRowAnimationAutomatic];
        [tableView reloadSectionIndexTitles];
    } else {
        [tableView deleteRowsAtIndexPaths:@[ip]
                         withRowAnimation:UITableViewRowAnimationAutomatic];
    }
}

The user can also delete a row by swiping it to summon its Delete button without having explicitly entered edit mode; no other row is editable, and no other editing controls are shown. This feature is implemented “for free” by virtue of our having supplied an implementation of tableView:commitEditingStyle:forRowAtIndexPath:. If you’re like me, your first response will be: “Thanks for the free functionality, Apple, and now how do I turn this off?” Because the Edit button is already using the UIViewController’s editing property to track edit mode, we can take advantage of this and refuse to let any cells be edited unless the view controller is in edit mode:

- (UITableViewCellEditingStyle)tableView:(UITableView *)aTableView
        editingStyleForRowAtIndexPath:(NSIndexPath *)indexPath {
    return self.editing ?
        UITableViewCellEditingStyleDelete : UITableViewCellEditingStyleNone;
}

A table item might have content that the user can edit directly, such as a UITextField (Chapter 23). Because the user is working in the view, you need a way to reflect the user’s changes into the model. This will probably involve putting yourself in contact with the interface objects where the user does the editing.

To illustrate, I’ll implement a table view cell with a text field that is editable when the cell is in editing mode. Imagine an app that maintains a list of names and phone numbers. A name and phone number are displayed as a grouped-style table, and they become editable when the user taps the Edit button (Figure 21.8).

Figure 21.8. A simple phone directory app

A UITextField is editable if its enabled is YES. To tie this to the cell’s editing state, it is probably simplest to implement a custom UITableViewCell class. I’ll call it MyCell, and I’ll design it in the nib, giving it a single UITextField that’s pointed to through a property called textField. In the code for MyCell, we override didTransitionToState:, as follows:

- (void) didTransitionToState:(UITableViewCellStateMask)state {
    [super didTransitionToState:state];
    if (state == UITableViewCellStateEditingMask) {
        self.textField.enabled = YES;
    }
    if (state == UITableViewCellStateDefaultMask) {
        self.textField.enabled = NO;
    }
}

In the table’s data source, we make ourselves the text field’s delegate when we create and configure the cell:

- (UITableViewCell *)tableView:(UITableView *)tableView
         cellForRowAtIndexPath:(NSIndexPath *)indexPath {
     MyCell* cell =
         (MyCell*)[tableView dequeueReusableCellWithIdentifier:@"Cell"
                                                  forIndexPath:indexPath];
     if (indexPath.section == 0)
         cell.textField.text = self.name;
     if (indexPath.section == 1) {
         cell.textField.text = self.numbers[indexPath.row];
         cell.textField.keyboardType = UIKeyboardTypeNumbersAndPunctuation;
     }
     cell.textField.delegate = self;
     return cell;
}

We are the UITextField’s delegate, so we are responsible for implementing the Return button in the keyboard to dismiss the keyboard:

- (BOOL)textFieldShouldReturn:(UITextField *)tf {
    [tf endEditing:YES];
    return NO;
}

When a text field stops editing, we are its delegate, so we can hear about it in textFieldDidEndEditing:. We work out which cell it belongs to, and update the model accordingly:

- (void)textFieldDidEndEditing:(UITextField *)tf {
    // some cell's text field has finished editing; which cell?
    UIView* v = tf;
    do {
        v = v.superview;
    } while (![v isKindOfClass: [UITableViewCell class]]);
    MyCell* cell = (MyCell*)v;
    // update data model to match
    NSIndexPath* ip = [self.tableView indexPathForCell:cell];
    if (ip.section == 1)
        self.numbers[ip.row] = cell.textField.text;
    else if (ip.section == 0)
        self.name = cell.textField.text;
}

You are unlikely to attach a plus (insert) button to every row. A more likely interface is that when a table is edited, every row has a minus button except the last row, which has a plus button; this shows the user that a new row can be inserted at the end of the table.

Figure 21.9. Phone directory app in editing mode

Let’s implement this for phone numbers in our name-and-phone-number app, allowing the user to give a person any quantity of phone numbers (Figure 21.9):

- (UITableViewCellEditingStyle)tableView:(UITableView *)tableView
           editingStyleForRowAtIndexPath:(NSIndexPath *)indexPath {
    if (indexPath.section == 1) {
        NSInteger ct =
            [self tableView:tableView numberOfRowsInSection:indexPath.section];
        if (ct-1 == indexPath.row)
            return UITableViewCellEditingStyleInsert;
        return UITableViewCellEditingStyleDelete;
    }
    return UITableViewCellEditingStyleNone;
}

The person’s name has no editing control (a person must have exactly one name), so we prevent it from indenting in edit mode:

- (BOOL)tableView:(UITableView *)tableView
        shouldIndentWhileEditingRowAtIndexPath:(NSIndexPath *)indexPath {
    if (indexPath.section == 1)
        return YES;
    return NO;
}

When the user taps an editing control, we must respond. We immediately force our text fields to cease editing: the user have may tapped the editing control while editing, and we want our model to contain the very latest changes, so this is effectively a way of causing our textFieldDidEndEditing: to be called. The model for our phone numbers is a mutable array of strings, numbers. We already know what to do when the tapped control is a delete button; things are similar when it’s an insert button, but we’ve a little more work to do. The new row will be empty, and it will be at the end of the table; so we append an empty string to the numbers model array, and then we insert a corresponding row at the end of the view. But now two successive rows have a plus button; the way to fix that is to reload the first of those rows. Finally, we also show the keyboard for the new, empty phone number, so that the user can start editing it immediately; we do that outside the update block:

- (void) tableView:(UITableView *)tableView
        commitEditingStyle:(UITableViewCellEditingStyle)editingStyle
        forRowAtIndexPath:(NSIndexPath *)indexPath {
    [tableView endEditing:YES];
    if (editingStyle == UITableViewCellEditingStyleInsert) {
        [self.numbers addObject: @""];
        NSInteger ct = [self.numbers count];
        [tableView beginUpdates];
        [tableView insertRowsAtIndexPaths:
         @[[NSIndexPath indexPathForRow: ct-1 inSection:1]]
                       withRowAnimation:UITableViewRowAnimationAutomatic];
        [self.tableView reloadRowsAtIndexPaths:
            @[[NSIndexPath indexPathForRow:ct-2 inSection:1]]
                          withRowAnimation:UITableViewRowAnimationAutomatic];
        [tableView endUpdates];
        // crucial that this next bit be *outside* the update block
        UITableViewCell* cell =
            [self.tableView cellForRowAtIndexPath:
                     [NSIndexPath indexPathForRow:ct-1 inSection:1]];
        [((MyCell*)cell).textField becomeFirstResponder];
    }
    if (editingStyle == UITableViewCellEditingStyleDelete) {
        [self.numbers removeObjectAtIndex:indexPath.row];
        [tableView beginUpdates];
        [tableView deleteRowsAtIndexPaths:@[indexPath]
                         withRowAnimation:UITableViewRowAnimationAutomatic];
        [tableView reloadSections:[NSIndexSet indexSetWithIndex:1]
                 withRowAnimation:UITableViewRowAnimationAutomatic];
        [tableView endUpdates];
    }
}

If the data source implements tableView:moveRowAtIndexPath:toIndexPath:, the table displays a reordering control at the right end of each row in editing mode (Figure 21.9), and the user can drag it to rearrange table items. The reordering control can be prevented for individual table items by implementing tableView:canMoveRowAtIndexPath:. The user is free to move rows that display a reordering control, but the delegate can limit where a row can be moved to by implementing tableView:targetIndexPathForMoveFromRowAtIndexPath:toProposedIndexPath:.

To illustrate, we’ll add to our name-and-phone-number app the ability to rearrange phone numbers. There must be multiple phone numbers to rearrange:

- (BOOL)tableView:(UITableView *)tableView
        canMoveRowAtIndexPath:(NSIndexPath *)indexPath {
    if (indexPath.section == 1 && [self.numbers count] > 1)
        return YES;
    return NO;
}

In our example, a phone number must not be moved out of its section, so we implement the delegate method to prevent this. We also take this opportunity to dismiss the keyboard if it is showing.

- (NSIndexPath *)tableView:(UITableView *)tableView
        targetIndexPathForMoveFromRowAtIndexPath:(NSIndexPath*)sourceIndexPath
        toProposedIndexPath:(NSIndexPath*)proposedDestinationIndexPath {
    [tableView endEditing:YES];
    if (proposedDestinationIndexPath.section == 0)
        return [NSIndexPath indexPathForRow:0 inSection:1];
    return proposedDestinationIndexPath;
}

After the user moves an item, tableView:moveRowAtIndexPath:toIndexPath: is called, and we trivially update the model to match. We also reload the table, to fix the editing controls:

- (void)tableView:(UITableView *)tableView
        moveRowAtIndexPath:(NSIndexPath *)fromIndexPath
               toIndexPath:(NSIndexPath *)toIndexPath {
    NSString* s = self.numbers[fromIndexPath.row];
    [self.numbers removeObjectAtIndex: fromIndexPath.row];
    [self.numbers insertObject:s atIndex: toIndexPath.row];
    [tableView reloadData];
}

We can rearrange a table not just in response to the user working in edit mode, but for some other reason entirely. In this way, many interesting and original interfaces are possible. In this example, we permit the user to double tap on a section header as a way of collapsing or expanding the section — that is, we’ll suppress or permit the display of the rows of the section, with a nice animation as the change takes place. (This idea is shamelessly stolen from a WWDC 2010 video.)

Presume that our data model once again consists of the two arrays, sectionNames and sectionData. I’ve also got an NSMutableSet, hiddenSections, in which I’ll list the sections that aren’t displaying their rows. That list is all I’ll need, since either a section is showing all its rows or it’s showing none of them:

- (NSInteger)tableView:(UITableView *)tableView
         numberOfRowsInSection:(NSInteger)section {
     if ([self.hiddenSections containsObject:@(section)])
         return 0;
     return [self.sectionData[section] count];
}

The section headers are a UITableViewHeaderFooterView with userInteractionEnabled set to YES and a UITapGestureRecognizer attached, so we can detect a double tap. Here’s how we respond to a double tap. We examine the tapped header to learn what section this is, and find out how many rows it has, as we’ll need to know that later, regardless of whether we’re about to show or hide rows. Then we look for the section number in our hiddenSections set. If it’s there, we’re about to display the rows, so we remove that section number from hiddenSections; now we work out the index paths of the rows we’re about to insert, and we insert them. If it’s not there, we’re about to hide the rows, so we insert that section number into hiddenSections; again, we work out the index paths of the rows we’re about to delete, and we delete them:

- (void) tap: (UIGestureRecognizer*) g {
    UITableViewHeaderFooterView* v = (id)g.view;
    NSString* s = v.textLabel.text;
    NSUInteger sec = [self.sectionNames indexOfObject:s];
    NSUInteger ct = [(NSArray*)(self.sectionData)[sec] count];
    NSNumber* secnum = @(sec);
    if ([self.hiddenSections containsObject:secnum]) {
        [self.hiddenSections removeObject:secnum];
        [self.tableView beginUpdates];
        NSMutableArray* arr = [NSMutableArray array];
        for (int ix = 0; ix < ct; ix ++) {
            NSIndexPath* ip = [NSIndexPath indexPathForRow:ix inSection:sec];
            [arr addObject: ip];
        }
        [self.tableView insertRowsAtIndexPaths:arr
            withRowAnimation:UITableViewRowAnimationAutomatic];
        [self.tableView endUpdates];
        [self.tableView scrollToRowAtIndexPath:[arr lastObject]
                              atScrollPosition:UITableViewScrollPositionNone
                                      animated:YES];
    } else {
        [self.hiddenSections addObject:secnum];
        [self.tableView beginUpdates];
        NSMutableArray* arr = [NSMutableArray array];
        for (int ix = 0; ix < ct; ix ++) {
            NSIndexPath* ip = [NSIndexPath indexPathForRow:ix inSection:sec];
            [arr addObject: ip];
        }
        [self.tableView deleteRowsAtIndexPaths:arr
            withRowAnimation:UITableViewRowAnimationAutomatic];
        [self.tableView endUpdates];
    }
}