Seasons change. People change. And user interfaces change, usually dynamically.
One dynamic change often seen in iOS apps is the addition or removal of a table cell to a UITableView. Often, you’ll see this when switching a UITableView from read-only to edit mode (for a dramatic example, try editing a contact in the Contacts app.) I’ve done this a few times in some of my iOS apps. I’ve found a few little tutorials out there that describe generally how to do this, but most contain some information gaps. Here, I’ll try to add some of the insight I gained.
I’ll use code examples from my most recent such app. In this app, I have a “Task Details” UITableView in which the user can view the details of a task (think: todo list item). They can also tap an Edit button to edit those details.
Tasks can contain, among other things, a detailed description. Whenever you’re editing a task, a large-ish UITableViewCell containing a UITextView is present, allowing the user to enter or modify a description. However, when in read-only mode, I wanted to remove the UITableViewCell that displays the task’s description if the task in fact has no description (otherwise, it’s wasted space).
The top part of the table view when we’re just looking at the Task. Note that the “Go Shopping” task has no description.
Tap the edit button, and the description cell appears. In the real app, of course, it’s animated.
One other important detail for our discussion is that tasks also have simple names. When in read-only mode, of course, I use a standard UITableViewCell (of style UITableViewCellStyleDefault) to display the task’s name. When in edit mode, however, I want to replace that default cell with a custom one containing a UITextField, in which the user can edit the task’s name.
The first thing I did was to create a method called isTaskDescriptionRow:
– (BOOL)isTaskDescriptionRow:(int) row {
if (tableView.editing) {
return row == TASK_BASICS_DESC_ROW;
} else {
if (taskDetailsCellIsShowing) {
return row == TASK_BASICS_DESC_ROW;
} else {
return NO;
}
}
}
taskDetailsCellIsShowing is a BOOL that should be self-explanatory. It gets set during the setEditing: animated: call, as shown a little ways below.
Next, I added code like the following to tableView: cellForRowAtIndexPath:
…
if (row == TASK_BASICS_NAME_ROW) {
if (tableView.editing) {
// create and return a table view cell containing
// a UITextField for editing the task’s name
} else {
// create and return a default table view cell
// displaying the task’s name
}
} else if ([self isTaskDescriptionRow:row]) {
UITableViewCell *cell = [[UITableViewCell alloc]
initWithStyle: UITableViewCellStyleDefault
reuseIdentifier: nil];
…
[descTextView release];
descTextView = [[UITextView alloc]
initWithFrame:CGRectMake(0, 0, w, h)];
// set descTextView to be non-editable and non-opaque
descTextView.text = task.description;
descTextView.userInteractionEnabled = !self.editing;
[cell.contentView addSubview: descTextView];
return cell;
} else…
Delegating to isTaskDescriptionRow: makes it easy to determine whether the current NSIndexPath should display the current task’s description. isTaskDescriptionRow: will return YES for the appropriate NSIndexPath if the UITableView is currently in edit mode, or if the current task has a description. If so, then I create a UITextView, configure it, and add it to the current table cell.
As I’d mentioned, when the current task has no description, I want the description row to be added when the table view is entering editing mode, and removed when reverting to read-only mode. This is done in the setEditing: animated: method:
– (void)setEditing:(BOOL)editing animated:(BOOL)animated {
[super setEditing:editing animated:YES];
[tableView setEditing:editing animated:YES];
if (editing) {
if (![self taskHasDescription]) {
[self addDescriptionRow];
} else {
[tableView reloadData];
}
} else {
if (![self taskHasDescription]) {
[self removeDescriptionRow];
} else {
[tableView reloadData];
}
}
[self.navigationItem setHidesBackButton:editing animated:YES];
…
}
After invoke setEditing: animated: on the super class as well as the UITableView itself, I check to see if in fact we’re entering editing mode (e.g. if editing = YES). If so, and if the current task does not have a description (i.e. if ![self taskHasDescription]), I invoke my addDescriptionRow method which I will show below. If we’re leaving editing mode, and the current task does not have a description, then I invoke removeDescriptionRow, also shown below:
-(void)addDescriptionRow {
[tableView beginUpdates];
taskDetailsCellIsShowing = YES;
NSIndexPath *idxPath =
[NSIndexPath indexPathForRow:TASK_BASICS_DESC_ROW
inSection:TASK_BASICS_SECTION];
NSArray *idxPaths = [NSArray arrayWithObject:idxPath];
[tableView insertRowsAtIndexPaths:idxPaths
withRowAnimation:UITableViewRowAnimationFade];
[tableView endUpdates];
}
-(void)removeDescriptionRow {
[tableView beginUpdates];
taskDetailsCellIsShowing = NO;
NSIndexPath *idxPath =
[NSIndexPath indexPathForRow:TASK_BASICS_DESC_ROW
inSection:TASK_BASICS_SECTION];
NSArray *idxPaths = [NSArray arrayWithObject:idxPath];
[tableView deleteRowsAtIndexPaths:idxPaths
withRowAnimation:UITableViewRowAnimationFade];
[tableView endUpdates];
}
The basic approach in the add and remove methods shown above is to create an array of indexPaths representing the cell(s) to be added or removed. You then pass that array to either insertRowsAtIndexPaths: withRowAnimation: or deleteRowsAtIndexPaths: withRowAnimation:. Finally, Apple’s documentation encourages insertions/deletions to be wrapped within beginUpdates and endUpdates calls, so I do that as well.
That all worked, for the most part; the description cell appeared as desired. But I noticed a bit of a wrinkle. The first tablecell–the one which displays the task’s name–is supposed to transform into an editable UITextField when the Edit button is tapped. But that wasn’t happening.
You can see in the code blocks above that this should be done in tableView: cellForRowAtIndexPath:. When the indexPath represents the task name row (section == TASK_BASICS_SECTION, row == TASK_BASICS_NAME_ROW), I then simply check the value of tableView.editing. If YES, I create a UITextField and add it to the UITableViewCell; if NO, I simply return a default UITableViewCell. Therefore, all I need to do is to add a call to tableView.reloadData in the setEditing: animated: method, right?
Wrong. When I did that, I received the following error:
Terminating app due to uncaught exception ‘NSInternalInconsistencyException’, reason: ‘Invalid update: invalid number of rows in section 0. The number of rows contained in an existing section after the update (3) must be equal to the number of rows contained in that section before the update (3), plus or minus the number of rows inserted or deleted from that section (1 inserted, 0 deleted).’
Hmm… time to look at my tableView: numberOfRowsInSection: method :
– (NSInteger)tableView:(UITableView *)tv numberOfRowsInSection:(NSInteger)section {
if (section == TASK_BASICS_SECTION) {
return [self numTaskDetailsBasicSectionTableRows];
} else …
}
}
Which delegates to this method:
– (int)numTaskDetailsBasicSectionTableRows {
if (tableView.isEditing) {
return NUM_TASK_DETAILS_BASIC_TABLE_ROWS;
} else {
if (taskDetailsCellIsShowing) {
return NUM_TASK_DETAILS_BASIC_TABLE_ROWS;
} else {
return NUM_TASK_DETAILS_BASIC_TABLE_ROWS – 1;
}
}
}
NUM_TASK_DETAILS_BASIC_TABLE_ROWS represents the number of rows in that top section when the description cell is being shown (i.e. 3). At the point where I call tableView.reloadData, however, it appears that the description cell hasn’t actually been added yet, at least as far as UIKit was concerned.
This led to my primary question: what exactly is UIKit doing when it adds a table view cell? Clearly, it needs to obtain information about the cell being added. This is especially apparent in this case, since the new cell is an atypical, custom cell, both in terms of its content and its height. Yet because the task name cell wasn’t being updated, it didn’t appear to be invoking tableView: cellForRowAtIndexPath: at any point while adding the new cell. So I set a breakpoint at the top of tableView: cellForRowAtIndexPath: to test my theory.
It turns out, UIKit was calling tableView: cellForRowAtIndexPath:. But only once. Specifically, it was calling it for the indexPath I provided in the addDescriptionRow method; i.e. the indexPath of the new description cell.
Pretty clever, actually.
But in my case, it was preventing that task-name cell from being updated. Thus, I still needed to call tableView.reloadData, but I needed to do it after the table cell addition was complete. At this point, I started scouring the documentation, as well as various online discussion forums. What I was looking for was some way to register a callback to be invoked when the table cell was completely added. Unfortunately, I couldn’t find any.
I played around a bit with reordering certain calls and and performing some calls asynchronously. I was able to get the functionality to work, but the animation wound up being far from smooth–quite jarring, in fact. I was also able to get the functionality to work without animation at all, but I really wanted the animation effect. I finally settled on the following:
– (void)setEditing:(BOOL)editing animated:(BOOL)animated {
… all the other stuff
if (![self taskHasDescription]) {
[self performSelector:@selector(reloadNameCell:)
withObject:[NSNumber numberWithInt:0]
afterDelay:0.33];
}
}
– (void)reloadNameCell:(NSNumber *)count {
@try {
NSIndexPath *ip = [NSIndexPath
indexPathForRow:TASK_BASICS_NAME_ROW
inSection:TASK_BASICS_SECTION];
[tableView reloadRowsAtIndexPaths:
[NSArray arrayWithObject:ip]
withRowAnimation:UITableViewRowAnimationNone];
}
@catch (NSException *exception) {
int i = [count intValue];
NSLog(@”Exception (%d) in reloading name cell, %@”,
i, [exception description]);
if (i < 5) {
[self performSelector:@selector(reloadNameCell:)
withObject:[NSNumber numberWithInt:i + 1]
afterDelay:0.125];
} else {
NSLog(@”Too many retries; aborting”);
}
}
}
If that looks like a hack, that’s because it is. Basically, we wait for 0.33 seconds, which seems to be just enough time for the call-adding animation to complete. We then invoke reloadNameCell: which at its core simply reloads the UITableViewCell that corresponds with the task name. We are also prepared to catch the abovementioned NSInternalInconsistencyException if we didn’t quite wait long enough. If we do catch that exception, we wait again for a short period of time and then try again. We track the number of retries and abort after 5 attempts; at that point, something really went wrong.
So there you have it. Hopefully that provides a little bit of insight as to what goes on under the hood while your UITableView’s structure is smoothly changing.