TweetFollow Us on Twitter

Takes All Sorts

Volume Number: 18 (2002)
Issue Number: 8
Column Tag: Mac OS X

Takes All Sorts

Make Your TableViews Autosort!

by Andrew C. Stone

One of the coolest pieces of object technology in the Cocoa bag of tricks is the NSTableView, and its daughter, NSOutlineView. The tableView lets you display a list of items with various properties. As in a spreadsheet, it displays rows of information - anything from simple text to graphics or even quicktime movies! Once you learn the fundamentals of the tableView and the outlineView, they'll quickly become some of your favorite user interface objects.

This article will take the NSTableView further, and show you how to add "auto sort" to your tableView, and the objects it represents. It assumes you have read the documentation for NSTableView and its companion class NSTableColumn and perhaps already have an app with an NSTableView of your own. You can try out this sort idea in Apple's Mail. A Mail Box shows a tableView of the list of messages, sender, subject, date, size, etc:


Figure 1. You can play with quick sort feature in Apple's Mail application.

When you click on the title cell of a column, an arrow appears to show direction of the sort, the cell is highlighted, and the messages are sorted on that key. If you click the title cell of that same column again, it toggles the sort to reverse its direction: if it was an ascending sort, now it's a descending sort. Sorting mail by subject is particularly interesting for deleting spam en masse!

When Time Equals Money...

When preparing TimeEqualsMoney 2.0 <http://www.stone.com/TimeEqualsMoney/> this spring, I decided users would love to be able to sort their time and expense entries on any key, in either direction with a simple click. So I reread the documentation Apple provides on the NSTableView class. I highly recommend actually reading the .h files! It's amazing how much stuff is already anticipated for you! There is a delegate method, - (void) tableView:(NSTableView*)tv didClickTableColumn:(NSTableColumn *)tableColumn. So, it seemed, I simply had to implement this method in my NSWindowController subclass, which is architecturally a sound choice for the NSTableView delegate. However, the method was simply not being called when I clicked on the column header cell. It turns out, and I noted this heavily in my code, that if neither column reodering nor column selection is selected in Interface Builder's NSTableView inspector, then the method is not called. Turning on column reordering was a simple fix and a desired feature! You can, of course, also call one of these methods programmatically with a parameter of YES:

- (void)setAllowsColumnReordering:(BOOL)flag;
- (void)setAllowsColumnSelection:(BOOL)flag;

Following on the Model-View-Controller pattern that I have discussed in previous articles on Cocoa architecture, I decided to store the sort column, and its direction in my NSDocument subclass, as well as make it responsible for the sorting of its items. This way, you can undo the sort, automatically mark the document as unsaved as well as save the sort between sessions. The user clicks the tableView column header, the window controller then sets the document's sort key, or direction if the key was already set to that column. Then the document tells itself to sort, which tells its NSMutableArray of entries to sort its contents. Finally, the document tells its window controllers to reload the tableView, which updates the interface to display the new sort order:


Figure 2. This tableView lets you click a column header to sort on that key - up or down.

Model Behavior

The implementation of the actual sort is trivial: just ask the list to sort itself based on asking its elements to sort using a selector: [list sortUsingSelector:@selector(compare:)];

During the list's sorting procedure, it repeatedly calls, in this case, compare: on one list item against another.

I like to just reuse the Kit's compare: which is implemented in NSString, NSDate, NSCell, NSValue, etc:

- (NSComparisonResult)compare:(id)other;

The NSComparisonResult has these three values: NSOrderedAscending = -1, NSOrderedSame = 0, NSOrderedDescending = 1. Since so many objects reply to compare:, you might implement it something like this in your data object, given that the sort key is the same string as the column identifiers, and you have various numbers, dates, strings and even booleans:

// the Data MODEL - the document has a list of these entities:
@interface PieceWork : NSObject <NSCopying>
{
    NSCalendarDate *startTime;
    NSString *description;
    NSTimeInterval timeOnJob;
    float _rate;
    BOOL paid;
    id owner;
...
}
- (NSComparisonResult)compare:(id)other;
- (void)setOwner:(id)ownsMe;
- (NSCalendarDate *)startTime;
- (NSTimeInterval)timeOnJob;
- (NSString *)workDescription;
- (float)hoursOnJob;
- (float)rate;
- (BOOL)paid;
...
@end
@implementation PieceWork
...
- (NSComparisonResult)compare:(id)other {
    BOOL isDescending = [owner sortIsDescending];
    NSString *key = [owner sortColumn];
   // now determine which one is first based on sort direction:
    PieceWork *first = isDescending ? other : self;
    if (first == other) other = self;
    
    if ([key isEqualToString:@"TimeOnJob"]) {
        return [[NSNumber numberWithFloat:[other timeOnJob]] compare: 
        [NSNumber numberWithFloat:[first timeOnJob]]];
    } else if ([key isEqualToString:@"Date"]) {
        return [[other startTime] compare: [first startTime]];
    } else if ([key isEqualToString:@"Description"]) {
// Very handy macro:
#define IS_NULL(s) (!s || [s isEqualToString:@""])
            if (IS_NULL([other workDescription])) return NSOrderedDescending;
            if (IS_NULL([first workDescription])) return NSOrderedAscending;
// people prefer upper and lower case mixed, unlike UNIX:
        return [[other workDescription] caseInsensitiveCompare:[first workDescription]];
    } else if ([key isEqualToString:@"Paid"]) {
        return [[NSNumber numberWithBool:[other paid]] compare:[NSNumber 
        numberWithBool:[first paid]]];
    }
    return 0;
}
@end

Here are the relevant instant variables and methods in the NSDocument subclass:

@interface MyDocument : NSDocument {
    NSMutableArray *_workList;
    NSString *_sortColumn;
    BOOL _sortIsDescending;
.   ...
}
- (void)sort;
- (NSArray *)workList;
- (void)setSortColumn:(NSString *)identifier;
- (NSString *)sortColumn;
- (void)setSortIsDescending:(BOOL)whichWay;
- (BOOL)sortIsDescending;
...
@end
@implementation MyDocument
...
- (void)sort:(NSMutableArray *)list {
    [list makeObjectsPerformSelector:@selector(setOwner:) withObject:self];
    [list sortUsingSelector:@selector(compare:)];  // asks us for how!!
}
- (void) sort {
    if (NOT_NULL(_sortColumn)) {
        [self sort:_workList];
        [[self windowControllers] makeObjectsPerformSelector:@selector(updateTotalsAndReload)];
    }
}
- (void)setSortColumn:(NSString *)identifier {
    if (![identifier isEqualToString:_sortColumn]) {
        [[[self undoManager] prepareWithInvocationTarget:self] setSortColumn:_sortColumn];
    [_sortColumn release];
    _sortColumn = [identifier copyWithZone:[self zone]];
        [[self undoManager] setActionName:NSLocalizedStringFromTable(@"Sort",@"TimeCard",@"title of 
        undo the sort action")];
    }
}
- (NSString *)sortColumn {
    return _sortColumn;
}
- (void)setSortIsDescending:(BOOL)whichWay {
    if (whichWay != _sortIsDescending) {
        [[[self undoManager] prepareWithInvocationTarget:self] setSortIsDescending:_sortIsDescending];
    _sortIsDescending = whichWay;
        [[self undoManager] setActionName:NSLocalizedStringFromTable(@"Sort 
        Direction",@"TimeCard",@"title of undo the sort up or down action")];
    }
}
- (BOOL)sortIsDescending {
    return _sortIsDescending;
}
- (NSArray *)workList { return _workList; }
- (void)setWorkList:(NSMutableArray *)list {
    [[[self undoManager] prepareWithInvocationTarget:self] setWorkList:_workList];
    [_workList release];
    if (NOT_NULL(_sortColumn)) [self sort:list];
    _workList = [list mutableCopyWithZone:[self zone]];
    [_workList makeObjectsPerformSelector:@selector(setOwner:) withObject:self];
    [[self windowControllers] makeObjectsPerformSelector:@selector(updateTotalsAndReload)];
    [[self undoManager] setActionName:NSLocalizedStringFromTable(@"Work Change", @"TimeCard", 
    @"Action name for changing worklist")];
}
// And don't forget to actually archive and read the sort info
// I highly recommended using human readable XML dictionaries:
- (NSMutableDictionary *)workDocumentDictionary {
    NSMutableDictionary *doc = [NSMutableDictionary dictionary];
        unsigned i, c = [_workList count];
        if (NOT_NULL(_sortColumn)) [doc setObject:_sortColumn forKey:SortNameKey];
        if (_sortIsDescending) [doc setObject:@"YES" forKey:SortDescendingKey];
       ...
       return doc;
}
- (BOOL)loadDataRepresentation:(NSData *)data ofType:
                                                      (NSString *)type {
    if ([type isEqualToString:DocumentType]) {
 NSDictionary *doc = [self workDocumentDictionaryFromData:data];
        id obj;
        ...
        obj = [doc objectForKey:SortNameKey];
        if (obj) {
            [self setSortColumn:obj];
        }
      obj = [doc objectForKey:SortDescendingKey];
        if (obj) {
            _sortIsDescending = [@"YES" isEqualToString:obj];
        }
        return YES;
  }
  return NO;
}
@end

Control Freak

Finally, we come to the meat of the matter in our NSWindowController subclass which is our NSTableView's dataSource as well as delegate.

@interface JobWindowController : NSWindowController 
{
    IBOutlet NSTableView *tableView;
    NSImage *descendingSortingImage;
    NSImage *ascendingSortingImage;
    ...
}

We have work to do in our window initialization method that gets called when the Interface has loaded, awakeFromNib. We want to get the images that we shall display when a sort is made. Using class-dump as described in my iPhoto Exporter bundle article <http://www.omnigroup.com/~nygard/Projects/index.html>, you might note that there are hidden, private Apple internal API to access the images to indicate ascending or descending sorts! Since one should absolutely never rely on hidden API to not dissolve into the ether in subsequent system releases, always bracket the use of these methods with a "respondsToSelector:" query, and provide backup images of your own:

- (void)awakeFromNib
{
    // private images:
    if ([[NSTableView class] respondsToSelector:@selector(_defaultTableHeaderSortImage)])
    ascendingSortingImage = [[NSTableView class] _defaultTableHeaderSortImage];
    else ascendingSortingImage = [[NSImage imageNamed:@"ascendingSort"] retain];
    if ([[NSTableView class] respondsToSelector:@selector(_defaultTableHeaderReverseSortImage)])
    descendingSortingImage = [[NSTableView class] _defaultTableHeaderReverseSortImage];
    else descendingSortingImage = [[NSImage imageNamed:@"descendingSort"] retain];
...
}

If you allow users to move and resize columns, then you definitely want to additionaly call these two methods in awakeFromNib - this will reestablish their preferences and give the system a name to save the column order and sizes.

    [tableView setAutosaveTableColumns:YES];
    [tableView setAutosaveName:@"WorkTable"];
    

So, now we're ready to implement the delegate method which gets called when the column title cell is clicked. The one fine point is that we want to make a note of which item was selected before the sort, so we can reselect it after the sort (its row number may have changed after the sort). We ask the tableView if it already has an image in that column, thus indicating that we need to toggle the direction, otherwise, we'll set the new sort key. The actual work of setting up the tableView's header hilighting is done in updateTableHeaderToMatchCurrentSort. This is factored into a separate method so we can also call it when loading a document to restore last saved sort state.

// BIG COCOA NOTE: if column reordering or column selection is not on
// then this doesn't get called!!
- (void) tableView:(NSTableView*)tv didClickTableColumn:(NSTableColumn *)tableColumn {
    NSImage *sortOrderImage = [tv indicatorImageInTableColumn:tableColumn];
    NSString *columnKey = [tableColumn identifier];
    MyDocument *doc = [self document];
    PieceWork *work = [self selectedWork];
    // If the user clicked the column which already has the sort indicator
    // then just flip the sort order.
    
    if (sortOrderImage || columnKey == [doc sortColumn]) {
        [doc setSortIsDescending:![doc sortIsDescending]]; 
    } else {
        [doc setSortColumn:columnKey];
    }
    [self updateTableHeaderToMatchCurrentSort];
    // now do it - doc calls us back when done
    [doc sort];
    // but reselect the one previously selected:
    if (work) [self selectWork:work];
}

This method updates the state of the NSTableColumn by first clearing all cells, and then setting the correct image and hilighting on the column to sort by, if any:

- (void)updateTableHeaderToMatchCurrentSort {
    BOOL isDescending = [[self document] sortIsDescending];
    NSString *key = [[self document] sortColumn];
    NSArray *a = [tableView tableColumns];
    NSTableColumn *column = [tableView tableColumnWithIdentifier:key];
    unsigned i = [a count];
    
    while (i-- > 0) [tableView setIndicatorImage:nil inTableColumn:[a objectAtIndex:i]];
    
    if (NOT_NULL(key)) {
        [tableView setIndicatorImage:(isDescending ? ascendingSortingImage:descendingSortingImage) 
        inTableColumn:column];
        
        [tableView setHighlightedTableColumn:column];
    } else [tableView setHighlightedTableColumn:nil];
}

And our helper functions to make the code neat and compact:

- (NSArray *)workList {
   return [[self document] workList];
}
- (void)updateTotalsAndReload {
// other ui:
//    [self updateTotals];
    [tableView reloadData];
}
- (PieceWork *)selectedWork {
   NSArray *workList = [self workList];
   int row = [tableView selectedRow];
   if (row > -1 && row < [workList count]) return [workList objectAtIndex:row];
   return nil;
}
- (void)selectWork:(PieceWork *)work {
    NSArray *a = [self workList];
    unsigned i = [a indexOfObject:work];
    if (i != NSNotFound) [self selectRow:i];
}

Devil in the Details

So, now we got sorting working, what sort of problems might we run into? Let's say a user edits the field of an entry in the sorted column. Upon finishing editing, they may have changed the relative order of that entry, requiring a new sort, and a reloading of the tableView again! We can check if we have the sorted column when the data gets set in - tableView:setObjectValue:forTableColumn:row:

- (void)tableView:(NSTableView *)tv setObjectValue:(id)object 
forTableColumn:(NSTableColumn *)tc row:(int)row;
{
        NSArray *workList = [self workList];
        NSString *ident = [tc identifier];
        if (tv == tableView) {
            PieceWork *work = [workList objectAtIndex:row];
            if ([ident isEqual:@"Description"]) {
                [work setWorkDescription:object];
                [self sortIfSortedOn:ident work:work];
           } else if ....
}

Isn't the devil in the details? Because the tableView will want to "select next" after setObjectValue: is called, the wrong row might be selected if the sort changed the currently selected item's row. By calling this method, we'll first end editing on the tableView so any inadvertent select next is foiled. Note the delay of 0.0 seconds which means to schedule the call of the method after the current event loop finishes:

- (void)afterSort:(PieceWork *)work {
    [[self window] makeFirstResponder:[self window]];
    [self selectWork:work];
}
- (void)sortIfSortedOn:(NSString *)ident work:(PieceWork *)work {
    if ([[[self document] sortColumn] isEqualToString:ident])  {
        int oldPosition
        [[self window] makeFirstResponder:[self window]];
        [[self document] sort];
        [self performSelector:@selector(afterSort:) withObject:work afterDelay:0.0];
    } else [self updateTotalsAndReload];
}

Conclusion

Sorting is something users expect tableViews to do now - and with a little effort, all of your tableViews can sort themselves!


Andrew Stone, andrew@stone.com, is Chief Chef at Stone Design, http://www.stone.com, has this to say about Cocoa and Stone Studio with all due respect to Gary Snyder's Turtle Island, "It's objects all the way down" .

 
AAPL
$95.60
Apple Inc.
-2.55
MSFT
$43.16
Microsoft Corpora
-0.42
GOOG
$571.60
Google Inc.
-15.82

MacTech Search:
Community Search:

Software Updates via MacUpdate

OneNote 15.2 - Free digital notebook fro...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that’s too important to forget. Whether you’re at... Read more
iStat Menus 4.22 - Monitor your system r...
iStat Menus lets you monitor your system right from the menubar. Included are 8 menu extras that let you monitor every aspect of your system. Some features: CPU -- Monitor cpu usage. 7 display... Read more
Ember 1.8 - Versatile digital scrapbook....
Ember (formerly LittleSnapper) is your digital scrapbook of things that inspire you: websites, photos, apps or other things. Just drag in images that you want to keep, organize them into relevant... Read more
OmniPlan 2.3.6 - Robust project manageme...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Command-C 1.1.1 - Clipboard sharing tool...
Command-C is a revolutionary app which makes easy to share your clipboard between iOS and OS X using your local WiFi network, even if the app is not currently opened. Copy anything (text, pictures,... Read more
Knock 1.1.7 - Unlock your Mac by knockin...
Knock is a faster, safer way to sign in. You keep your iPhone with you all the time. Now you can use it as a password. You never have to open the app -- just knock on your phone twice, even when it's... Read more
Mellel 3.3.6 - Powerful word processor w...
Mellel is the leading word processor for OS X and has been widely considered the industry standard since its inception. Mellel focuses on writers and scholars for technical writing and multilingual... Read more
LibreOffice 4.3.0.4 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
Freeway Pro 7.0 - Drag-and-drop Web desi...
Freeway Pro lets you build websites with speed and precision... without writing a line of code! With it's user-oriented drag-and-drop interface, Freeway Pro helps you piece together the website of... Read more
Drive Genius 3.2.4 - Powerful system uti...
Drive Genius is an OS X utility designed to provide unsurpassed storage management. Featuring an easy-to-use interface, Drive Genius is packed with powerful tools such as a drive optimizer, a... Read more

Latest Forum Discussions

See All

Dawn of the Immortals Review
Dawn of the Immortals Review By Jennifer Allen on July 31st, 2014 Our Rating: :: RESPECTABLE EXPLORATIONUniversal App - Designed for iPhone and iPad Dawn of the Immortals might not re-invent the wheel, but it does tweak it a little... | Read more »
80 Days Review
80 Days Review By Jennifer Allen on July 31st, 2014 Our Rating: :: EPIC ADVENTUREUniversal App - Designed for iPhone and iPad A fantastic and fascinating re-envisioning of the classic novel by Jules Verne, 80 Days is a delightful... | Read more »
Battleheart Legacy Guide
The world of Battleheart Legacy is fun and deep; full of wizards, warriors, and witches. Here are some tips and tactics to help you get the most enjoyment out of this great game. | Read more »
Puzzle Roo Review
Puzzle Roo Review By Jennifer Allen on July 31st, 2014 Our Rating: :: PUZZLE-BASED TWISTUniversal App - Designed for iPhone and iPad A different take on the usual block dropping puzzle game, Puzzle Roo is quite pleasant.   | Read more »
Super Crossfire Re-Release Super Crossfi...
Super Crossfire Re-Release Super Crossfighter Coming Soon, Other Radiangames Titles Go 50% Off Posted by Ellis Spice on July 31st, 2014 [ | Read more »
Hexiled Review
Hexiled Review By Rob Thomas on July 31st, 2014 Our Rating: :: HEX SELLSUniversal App - Designed for iPhone and iPad In space, no one can hear you… spell? Hexiled is a neat concept for a word scramble puzzle, but it doesn’t go too... | Read more »
Summoners War: Sky Arena Passes 10 Milli...
Summoners War: Sky Arena Passes 10 Million Installs! Posted by Jessica Fisher on July 31st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Deep Loot Review
Deep Loot Review By Jennifer Allen on July 31st, 2014 Our Rating: :: DIVE DEEPUniversal App - Designed for iPhone and iPad Dive deep in this fun explore-em-up that’s a little grind heavy but ultimately quite entertaining.   | Read more »
Despicable Me: Minion Rush is One Year O...
Despicable Me: Minion Rush is One Year Old, Gets its Biggest Update Yet Posted by Jennifer Allen on July 31st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Fish & Shark Review
Fish & Shark Review By Jordan Minor on July 31st, 2014 Our Rating: :: FLAPPY FISHUniversal App - Designed for iPhone and iPad Fish & Shark’s beauty is only scale deep.   | Read more »

Price Scanner via MacPrices.net

All Over For Tablets Or Just A Maturing, Evol...
CNN’s David Goldman weighs in on tablet sector doom and gloom, asking rhetorically: “Is this the beginning of the end for the tablet?” Answering that, he contends that hysteria and panic are... Read more
Letterspace 1.0.1 – New Free iOS Text Editor...
Bangkok, Thailand based independent developer Sittipon Simasanti has released Letterspace, a new text editor for iPhone, iPad, and iPod touch devices. Letterspace is a note taking app with an... Read more
Save up to $130 on an iPad mini with Apple re...
The Apple Store has Certified Refurbished 2nd generation iPad minis with Retina Displays available for up to $130 off the cost of new models, starting at $339. Apple’s one-year warranty is included... Read more
iPad Cannibalization Threat “Overblown”
Seeking Alpha’s Kevin Greenhalgh observes that while many commentators think Apple’s forthcoming 5.5-inch panel iPhone 6 will cannibalize iPad sales, in his estimation, these concerns are being... Read more
Primate Labs Releases July 2014 MacBook Pro P...
Primate Labs’ John Poole has posted Geekbench 3 results for most of the new MacBook Pro models that Apple released on Tuesday. Poole observes that overall performance improvements for the new MacBook... Read more
Apple Re-Releases Bugfixed MacBook Air EFI Fi...
Apple has posted a bugfixed version EFI Firmware Update 2.9 a for MacBook Air (Mid 2011) models. The update addresses an issue where systems may take longer to wake from sleep than expected, and... Read more
Save $50 on the 2.5GHz Mac mini, plus free sh...
B&H Photo has the 2.5GHz Mac mini on sale for $549.99 including free shipping. That’s $50 off MSRP, and B&H will also include a free copy of Parallels Desktop software. NY sales tax only. Read more
Save up to $140 on an iPad Air with Apple ref...
Apple is offering Certified Refurbished iPad Airs for up to $140 off MSRP. Apple’s one-year warranty is included with each model, and shipping is free. Stock tends to come and go with some of these... Read more
$250 price drop on leftover 15-inch Retina Ma...
B&H Photo has dropped prices on 2013 15″ Retina MacBook Pros by $250 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.3GHz Retina MacBook Pro: $2249, $250 off... Read more
More iPad Upgrade Musings – The ‘Book Mystiqu...
Much discussed recently, what with Apple reporting iPad sales shrinkage over two consecutive quarters, is that it had apparently been widely assumed that tablet users would follow a two-year hardware... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.