Volume Number: 18 (2002)
Issue Number: 9
Column Tag: Cocoa Development

Table Techniques Taught Tastefully (part 1)

Using NSTableView for Real-World Applications

by Dan Wood

One of the most useful and powerful displays any desktop application can have is a table of data. Before Cocoa came along, table display was high on the difficulty scale. Now with NSTableView, simple display of table data is almost trivially easy. With minimal effort, it's possible to get advanced display capabilities and functionality as well, the kind you would expect to find in full-featured "professional" programs.

When you make use of an NSTableView in your program, you control a scrollable grid of rows and columns, each cell containing text or other items. Column resizing and rearranging comes "for free," and text cells can be edited. What an NSTableView is not applicable for is a hierarchical outline (use an NSOutlineView for that), variable-height rows like you would find in an HTML table display, or cell-based display and selection like you would find in a spreadsheet. If you're going that far outside of the base functionality of NSTableView, you may find yourself needing to "roll your own" class, or perhaps start out with a more sophisticated base class. But with a little guidance from this article and perhaps other sources as well, you should be able to use NSTableView for just about any reasonable need.

This is the first of a multiple-part series of articles; the first one starts out with the basics, just to get the reader up to speed on how to use NSTableView, and then dives into a few techniques that I have picked up to add zest to your tables. By the end of this article, you should be familiar with basic techniques of displaying and editing tables along with methods to display more than just plain text and manipulating table column widths. By the end of the series, you will also have in your toolkit more advanced techniques such as alphabetic type-ahead, display of buttons and graphics, sorting, drag and drop, striping alternate rows, and building custom subclasses. You can pick and choose which of these are applicable for your program.

I've built a "TableTester" application (See figure 1; downloadable at www.karelia.com/tabletester/) that shows off most of the table features described in this series. The display is a single window with a number of tab views; the table in each tab view shows off one or more features described here.

TableTester is constructed in such a way as to separate the table functionality from the implementation details as much as possible, making each class (for data source, delegate, or subclassing NSTableView) easy to read.

Naming conventions in the code should be noted, however. Being an old PowerPlant developer, I got used to prefixes on variables to distinguish local variables from other types, and I've carried this over into the world of Cocoa. Prefixes m, o, s, g stand for member (instance) variable, outlet (also an instance variable), static variable, and global variable. Parameters passed into functions typically begin with in as well. This way, it's easy to glance at my code and know what kind of variable I'm looking at. For example, oTable refers to an outlet to the NSTableView object used by a delegate; oData is an outlet to the data array. Feel free to adapt or disdain these conventions.

To build up the sample table data, I've stored some test data in TSV (tab-separated value) files, and I've included a category method on NSString, -(NSArray *) arrayFromTSV, to read the file into memory. (The implementation of this method is not listed here, for lack of relevance, but it can be found in the project's source code.)

There are three "entry points" that you have to control how your NSTableView will look and act. These are listed in the order of complexity and specialization.

• The Data Source. Each NSTableView must have an object connected to its dataSource outlet; this connection is usually made through Interface Builder. This is an object that contains methods listed in the NSTableDataSource informal protocol. At the minimum, this is how a table gets its data to display; table editing and drag & drop is handled using this connection as well.

• The Delegate. An NSTableView can connect to a delegate object (usually the same object as the data source in your code) to notify your code before and after certain events. Using a delegate is optional, but it gives your code much finer control over how a table is displayed and how it responds to user activity. We will begin exploring uses for the delegate in the second half of this article.

• Subclassing NSTableView. Cocoa objects often do not need to be subclassed to be useful, but if you have any needs that the base class can't handle, there are a number of places you can customize a table's look and behavior in subtle or radical ways. Later in this series, we will showcase some subclasses that you can use for your purposes; these are built in such a way to encourage the Model-View-Controller separation that is made easy by the architecture of Cocoa.

The absolute minimum that a table can do is display data, and in order to accomplish this, you must implement two methods in your "data source" class: numberOfRowsInTableView: and tableView: objectValueForTableColumn: row:.

The former method is called whenever the table view needs to know how many rows are in your table. It is invoked quite frequently, so you should be sure to have an efficient implementation. If your data structure that your table accesses is complex and it takes a while just to calculate the size of it, you should probably cache the size and return that cached value in your implementation of this method.

The latter method is called to display the contents of a given row and column in the table, but it only is called for cells that are actually visible. If you have a table with 5000 rows, but only twenty rows (and all three columns) are visible at a time in the enclosing scroll view, then this method will only be called 20 * 3 = 60 times. Your method should still be as efficient as possible for accessing data; if the data cannot be retrieved immediately (for instance, if they must be retrieved over the network), it may make sense to return placeholder values and then refresh the table display after the data arrive.

TableTester uses a simple array, each element corresponding to a row in the table, so returning the row count is as simple as retrieving the array count. Each element in the array is a dictionary, so we make a point of setting the identifier of each table column to correspond to the key of the dictionary. This is illustrated in figure 2. Getting the value is then a matter of getting the appropriate dictionary for the given row, and then getting the value from the dictionary based on the column identifier. (If your code only controls one table, then you can ignore the NSTableView parameter; otherwise you could compare with the tables your code manages.) This is a typical approach (but by no means the only one) to populating a table view, useful because it allows table columns to be arranged in any order without being affected by the structure of the underlying data. (See listing 1.)

numberOfRowsInTableView:
Return the number of rows in the entire table by retrieving the data array's count.
- (int)numberOfRowsInTableView:(NSTableView *)inTableView
{                                    
   return [oData count];                  
}                                    

tableView: objectValueForTableColumn: row:
Return the string at the given row and column by fetching the row from the array, and then fetching 
the appropriately keyed string based on the column identifier.

- (id)tableView:(NSTableView *)inTableView      
      objectValueForTableColumn:(NSTableColumn*)inTableColumn
      row:(int)inRowIndex                     
{                                    
   NSDictionary *dict = [oData objectAtIndex:inRowIndex];
   return [dict objectForKey:[inTableColumn identifier]];
}                                    

If you wish to make the data in your table editable, you need to make sure that the table column is set to be editable from within Interface Builder, and you need to implement tableView: setObjectValue: forTableColumn: row: in your table's data source. NSTableView handles the rest, responding to a double-click in a cell and sending the message to your data source after the value has changed.

TableTester relies on the fact that the data is actually stored in mutable dictionaries, along with the correspondence between column identifiers and dictionary keys mentioned above. See listing 2.

tableView: setObjectValue: forTableColumn: row:
Update the dictionary corresponding to the given row by setting the string keyed by the column 
identifier to the given value.

- (void)tableView:(NSTableView *)inTableView
     setObjectValue:(id)inObject
     forTableColumn:(NSTableColumn *)inTableColumn
     row:(int)inRowIndex
{
   NSMutableDictionary *dict
      = [oData objectAtIndex:inRowIndex];
   [dict setObject:inObject forKey:
      [inTableColumn identifier]];
}

How do you let the user add and delete rows? Every application handles the user interface differently: some have little + and - buttons near the table, some have a separate field for entering data with a button to add the contents of the fields into the table; some go for a truly minimalist approach, avoiding the need for additional screen space. Here we show how to add a new row using a small button in the upper right corner of the table view itself (in a space that would otherwise be unused; see figure 3) that programmatically activates the table for editing your new row.

To place a little button in the upper corner of the table, you can use Interface Builder. Create a custom view in your nib, and put a small button (about 12 pixels square) into the view. Then hook up that button to the table view's cornerView outlet. Hook up the button's action to your method to invoke when the button is clicked.

(A note about the corner view: It's tricky to get it to look just right. A more sophisticated approach than connecting to the outlet is to position the button in code as a subview of the default view, which takes care of displaying the gradient. You may need to experiment with the button type in order for it to preserve the background gradient; a "toggle" button seems to do the trick.)

To jump into editing mode, you need to select the row you will be editing, and then invoke editColumn: row: withEvent: select:. This example (listing 3) adds a new empty item to the data array, then starts editing the leftmost column.

doAdd:
Creates an empty row's dictionary and adds it to the end of the data array.  The selection is changed 
to this new last row, and we enter editing mode.

- (IBAction) doAdd:(id)sender
{
   NSMutableDictionary *newRow
      = [NSMutableDictionary dictionary];   // an empty dictionary
   int rowNum = [oData count];
   [oData addObject:newRow];   // Add an empty object to the data array
   [oTable selectRow:rowNum byExtendingSelection:NO];
   [oTable editColumn:0 row:rowNum withEvent:nil
      select:YES];
}

No matter what the user interface, you will need to implement an action method that loops through each selected row using selectedRowEnumerator. Deleting elements from an NSMutableArray is a little tricky, since you can't delete elements from an NSMutableArray from within an enumerator. In our sample (listing 4), we replace each row to delete with the special placeholder [NSNull null] and then delete those values afterwards in a single operation. You can have the delete: action method connected to a button and/or have it respond to the Delete menu. The only trick is that the current version of Interface Builder has the Delete menu item sending the clear: action. If your program has text editing anywhere, and you want the user to ue the Delete menu to clear text, then you will have to reconcile this! Using Interface Builder, you should change the menu item to send delete: to the first responder, so your delete: method will be invoked, and so that the menu item will also function on any editable text you may have in your program, which also implements a delete: method.

In our example code, we have a method implemented in the controller to actually perform the deletion, to encourage separation between the view and the controller. Our delete: method sends the method deleteSelectedRowsInTableView to that controller.

deleteSelectedRowsInTableView:
For each selected row number, replace the data element with the special null placeholder value.  
Afterwards, clear out those values in one operation, and redisplay the data.

- (void) deleteSelectedRowsInTableView:
      (NSTableView *)inTableView
{
   int row = [inTableView selectedRow];   // get the last-selected row
   if (row >= 0)
   {
      // Replace each selected row data with special null placeholder
      NSEnumerator *theEnum
         = [inTableView selectedRowEnumerator];
      id theItem;
      while (nil != (theItem = [theEnum nextObject]) )
      {
         int row = [theItem intValue];
         [oData replaceObjectAtIndex:row withObject:
            [NSNull null]];
      }
      // Now, remove the NSNull placeholders
      [oData removeObjectIdenticalTo:[NSNull null]];
      [inTableView deselectAll:nil];
      [inTableView reloadData];
   }
}

delete:
Respond to the user action (from a button or menu) by passing along the request to the table's data 
source.

- (IBAction) delete:(id)sender
{
   [[oTable dataSource]
      deleteSelectedRowsInTableView:oTable];
}

Many tables need to do something when the user selects a row, or perhaps when the user double-clicks on a row. NSTableView, like other views, has the ability to associate an action with a click to invoke a particular method; you would "wire up" an action in Interface Builder using techniques that are (hopefully!) familiar to you by now.

But there is a problem with using the action associated with a table: your code only gets called when the user clicks on a row on the table. If the user is using the keyboard to move up and down the rows of the table, nothing happens. If you want the display to reflect the currently selected row in your table, you need a better solution.

To handle a row selection change even by keyboard, the better approach is to make use of the delegate model. (Plus, more than one object can be watching for this change; an action will only be sent to one controller.) If your NSTableView has an object connected to the delegate outlet, certain messages are sent to that object before, during, or after strategic operations, to give your program finer control over its behavior. So what we want to do is hook up the delegate in our nib file, and implement tableViewSelectionDidChange: in that delegate object. The implementation of this method will handle any change in a row selection, and usually does what you would expect. (In some situations, you might even want to respond to a click with an action method as well as using the delegate method; that's fine too.)

In TableTester, we find a URL to display from the table's underlying data, and populate an NSTextField with that URL. Whenever the user clicks on a new row, or changes the selection using the arrow keys, the URL display changes appropriately.

selectedRowURL
Return a URL associated with the selected row in the table (if any) by looking up the appropriate 
dictionary object in the data array, and getting the string associated with the "url" key.

- (NSString *) selectedRowURL
{
   NSString *result = nil;
   int row = [oTable selectedRow];
   if (row >= 0)
   {
      result
         = [[oData objectAtIndex:row] objectForKey:@"url"];
   }
   return result;
}

tableViewSelectionDidChange:
Respond to the delegate message that the selection in the table has changed by fetching the URL 
string associated with the selected row, and putting that string in the text field hooked up to the 
oURLField outlet.

- (void)tableViewSelectionDidChange:
      (NSNotification *)aNotification
{
   [oURLField setObjectValue:[self selectedRowURL]];
}

What about double-clicking? To invoke a method when the user double-clicks on a row, you need to insert a little bit of code somewhere (such as your awakeFromNib method) to connect the target and the "double action" to the appropriate object and method.

    [oTable setTarget:self];
    [oTable setDoubleAction:@selector(openSelectedRow:)];

A table view, to display itself, uses a single cell -- an NSTextFieldCell, for text display -- for each column; this cell is used repeatedly to display each row. With this in mind, we can customize the display of each table column's rows by modifying its associated cell.

In our TableTester program (under the "Wrapping" tab), we set all of the column cells to wrap their text. Additionally, we find the "description" column, and set its font to be a smaller size. A good place to accomplish this is in the awakeFromNib method, which is invoked after the table view has loaded but before it tries to display anything.

awakeFromNib
Set all of the table's columns to wrap their text to multiple lines; Permanently make the 
"description" column display with a small font.

- (void)awakeFromNib
{
   NSEnumerator *theEnum
      = [[oTable tableColumns] objectEnumerator];
   NSTableColumn *theCol;
   while (nil != (theCol = [theEnum nextObject]) )
   {
      [[theCol dataCell] setWraps:YES];
   }
   // now change the "description" column's cell
   theCol
      = [oTable tableColumnWithIdentifier:@"description"];
   [[theCol dataCell] setFont:
      [NSFont systemFontOfSize:
         [NSFont smallSystemFontSize]]];
}

But what about if you want to change attributes for a cell depending upon the row you are displaying? Returning the NSString to display in each cell using tableView: objectValueForTableColumn: row: doesn't give you control over a cell's display. (One technique would be to build an NSAttributedString, but you may wish to adjust other cell properties such as the background color.) A solution is to have your code implement the delegate method tableView: willDisplayCell: forTableColumn: row:. This message is sent to your delegate object right before each cell is about to be displayed, and you can act upon it to change attributes of the cell that is reused for each row.

tableView: willDisplayCell: forTableColumn: row:
Modify the cell's color and font depending on the publisher and the price.
- (void)tableView:(NSTableView *)inTableView
    willDisplayCell:(id)inCell
     forTableColumn:(NSTableColumn *)inTableColumn
                    row:(int)inRow
{
   NSDictionary *dict = [oData objectAtIndex:inRow];
   // Make the row's text in any column be red if the publisher is Karelia; black otherwise
   BOOL karelia
      = [[dict objectForKey:@"publisher"]
            isEqualToString:@"Karelia"];
   [inCell setTextColor:
      (karelia ? [NSColor redColor] : [NSColor blackColor])];
   // Modify the cell for the "price" column
   if ([[inTableColumn identifier]
            isEqualToString:@"price"])
   {
      if ([[dict objectForKey:@"price"]
         isEqualToString:@"free"])
      {
         // Make the price text bold if it's free
         [inCell setFont:
            [NSFont boldSystemFontOfSize:
               [NSFont systemFontSize]]];
      }
      else
      {
         // Otherwise, just use regular system font
         [inCell setFont:
            [NSFont systemFontOfSize:[NSFont systemFontSize]]];
      }
   }
}

TableTester (under the "Attributed" tab) checks the column that is about to be displayed, and changes attributes of the text cell for certain columns. The listing below causes all "free" software prices to be shown in boldface and all software from Karelia in red. Note that you always have to be able to set the attributes back to their other state; since the cells are reused for each column, setting a cell's style but not setting it back would have strange display results. The result of applying the code from listing 6 and listing 7 is shown here in figure 4.

When you resize a window containing a table set to grow as the window grows, your application needs to appropriately resize the table columns. You can check the "autoresizing" flag for the table view in your nib file to cause all columns to proportionally resize as you resize the table; if it's not checked, the last column will grow as the table grows. You can also make use of the maximum and minimum column widths in order to constrain columns to a certain size. But this is often not good enough; what if you want certain columns to shrink and grow in some particular proportions? The solution is to write a little code to resize the columns for you according to your needs.

To respond to resizing table views, you need to respond to the NSViewFrameDidChangeNotification that is sent to the delegate by the scroll view that holds the table view. A good place to set this up is in your awakeFromNib method, as we do here. (Note that in this sample, we also rebuild the table columns immediately so they will start out with the right size.)

When your delegate receives the notification, it should calculate the column sizes based upon the width of the entire table, the columns, and the spacing between the columns. You can set new widths for the columns as appropriate. (TableTester, as an unrealistic example, holds the first column at a constant value and sizes the remaining columns proportionally.)

awakeFromNib
Start the table's scrollView listening to the NSViewFrameDidChangeNotification, and set the column 
widths initially.

- (void)awakeFromNib
{
   [[NSNotificationCenter defaultCenter]
      addObserver:self
         selector:@selector(rebuildTable:)
            name:NSViewFrameDidChangeNotification
          object:[oTable enclosingScrollView]];
   [self rebuildTable:nil];      // force an initial rebuild
}

rebuildTable
Set the widths of the table columns.  The first column gets a constant width; the rest of the columns
divide up the remaining space.

- (void) rebuildTable:(NSNotification *)inNotification
{
   NSArray *columns = [oTable tableColumns];
   int numberOfColumns = [columns count];
   float spacingWidth = [oTable intercellSpacing].width;
   float tableWidth = [oTable bounds].size.width;
   float firstColWidth = 200.0;      // constant width for first column
   // Calculate the width of the other table columns by dividing up remaining space
   float remWidth
      = tableWidth - firstColWidth - spacingWidth;
   float colWidth
      = (remWidth / (numberOfColumns-1)) - spacingWidth;
   int i;
   // First, set the first column to a constant value
   [[columns objectAtIndex:0] setWidth:firstColWidth];
   // Now, set the rest of the columns starting at index 1
   for ( i = 1 ; i < numberOfColumns ; i++ )
   {
      NSTableColumn *column = [columns objectAtIndex:i];
      [column setWidth:colWidth];
   }
}

Your table-rebuilding code could even add or delete table columns programmatically, causing the number of columns across to adjust as the size changes. One caveat: NSTableColumn objects created with the [[NSTableColumn alloc] initWithIdentifier:@"foo"] technique will have different display properties than those created in Interface Builder, so you may need to adjust your font heights in code if you use this technique.

A capability that comes for free with table views, if you make the effort to turn it on in your code, is saving of column widths and positions in your preferences file for you automatically. (There's a spot to set this in Interface Builder, but as of this writing, it is disabled and nonfunctional.) By providing a name to distinguish one table from another in the preferences file, and turning on the auto-saving feature, any column adjustment is saved and restored for you. The two lines here, placed for example in the awakeFromNib method, are all you need. In TableTester, this feature is demonstrated in the table under the "Attributed" tab.

   [oTable setAutosaveName:@"my table"];
   [oTable setAutosaveTableColumns:YES];

One thing to watch out for if you save your table columns: If you later decide to remove or rename a column, and your users have the table column positions stored in their application defaults, they may run into problems. As NSTableView reads the preferences and builds the table according to those settings, it will "choke" if it finds a column identifier that it no longer exists, causing missing columns or exception to be thrown. So if you are releasing an update to an application where table columns were saved, be sure to keep your table columns around in Interface Builder, and remove or rename them programmatically.

If you've followed along, you should have a pretty good understanding of how to display data in an NSTableView, and a few tricks of the trade for editing its contents, controlling display of the cells, and manipulating the columns. Certainly this is good enough for a basic program. But there are so many more cool things you can do with NSTableView, and this is why there's more to come. Tune in next month for part two, in which we'll cover more options for deleting rows, alphabetic type-ahead, display of non-text cells, sorting, drag and drop, and clipboard support.

Dan Wood once took an introductory Arabic class, but nobody in the room knew what language they were being taught. He likes to buy fruits and vegetables from the farmer's market on Tuesday mornings. He missed the last two days of WWDC this year due to the birth of his son. He is the author of Watson, an application written in Cocoa. Dan thanks Chuck Pisula at Apple for his technical help with this series, and acknowledges online code fragments from John C. Randolph, Stephane Sudre, Ondra Cada, Vince DeMarco, Harry Emmanuel, and others. You can reach him at dwood@karelia.com.