Alex Rozanski

Introducing PXSourceList 2

About four years ago I built and released my first open-source Cocoa project, PXSourceList. It’s amazing how different the Cocoa open-source community was back then compared to today – there weren’t many Cocoa projects open-sourced on GitHub1 and tools like CocoaPods didn’t yet exist. When building PXSourceList, I also stumbled across the then, relatively little-known documentation tool, appledoc2, which I used to document PXSourceList.

I was quite frankly astounded by the reception that PXSourceList received when it was released, and it was well-received at a small lunchtime blitz talk at NSConference 2010, where I played with fire by demonstrating how easy it was to set up PXSourceList in a project in a live coding session3. I was even thanked and congratulated profusely by a Welsh gentleman later at the bar who was severely inebriated (I apologise for forgetting your name; if you’re reading this, I was very touched).

Unfortunately PXSourceList hasn’t had the love it’s deserved over the past few years, and I wanted to fix that. I’ve been working on PXSourceList 2 over the last couple of months, and I’m finally happy to release it!

TL;DR

  • PXSourceList now has view-based table support with extra classes included with the project to make configuring table cell views quick and easy.
  • A new, generic, PXSourceListItem data model class has been included with the project for use by PXSourceList data source objects so you don’t have to roll your own.
  • Bugs relating to some PXSourceList delegate and data source methods not being called has been fixed, with a shiny new proxy-based implementation under the hood.
  • For more information, read the release notes (which includes API changes), and view the project on GitHub!

Compatibility

PXSourceList previously required the OS X 10.5 SDK and above, but PXSourceList 2 requires the OS X 10.7 SDK.

Cell-based table support is still supported by PXSourceList 2, and projects that use PXSourceList 0.x and 1.x will still work with PXSourceList 2 in almost all cases4.

View-based Tables

One of the biggest enhancements to PXSourceList 2 has been the addition of view-based table support (something that was begging to be implemented since it was added to NSTableView and NSOutlineView back in Lion). Extra delegate methods have been added to PXSourceListDelegate (including -sourceList:viewForItem: and -sourceList:rowViewForItem:) to support this new functionality.

One of the main goals of PXSourceList when I started the project was making it as easy as possible to implement an idiomatic Source List, with as little setup and configuration as possible. I feel like I achieved this with 0.x and 1.x, and adding badges and icons to cells was really simple, only involving overriding a few data source methods.

One problem that view-based tables pose for setting up icons and badges is that the design of each table cell in the Source List is now put into the hands of the developer, and displaying icons and badges is not quite as simple as it was when working with NSCells (which was done in PXSourceList with custom drawing). To help in setting up your own table cell views for use with PXSourceList, version 2 includes two new classes:

  1. PXSourceListBadgeView: an NSControl subclass which draws badges. Its backing cell5 is used when PXSourceList is configured in cell-based mode, but it can also be used in NSTableCellViews when using PXSourceList in view-based mode to draw badges with the idiomatic white-on-grey-blue Source List badge colours.
  2. PXSourceListTableCellView: an NSTableCellView subclass which includes a badgeView outlet for connecting up a PXSourceListBadgeView object in Interface Builder. Along with NSTableCellView’s textField and imageView properties, this class should give you everything you need in most cases to set up Source List cells without any subclassing.

PXSourceList has traditionally had a very opinionated design by doing all of the custom drawing and layout for you without much customisation; I decided that I wanted to be less interventional with PXSourceList 2, and have followed the spirit of NSTableCellView (which exposes textField and imageView outlets which you need to configure yourself) in declaring a badgeView outlet in PXSourceListTableCellView which you set up yourself. However, like NSTableCellView (with its textField and badgeView outlets), PXSourceListTableCellView will lay out the badgeView for you at a default position in -layout.

New Example App

A shiny new view-based Source List example app has been added to the project which should give you a practical idea of how to use a view-based Source List in your own applications. It also includes a drag-and-drop example using the view-based table in-place row modification methods such as -insertRowsAtIndexes:withAnimation:.

PXSourceListItem

When building a source list (or outline view) data source, you usually build up a tree structure of model data which represents all of the items in your source list, and also corresponds to the organisation of these items in the source list.

PXSourceList 0.x and 1.x shipped with a SourceListItem class which was used for the demo project as an example of how you could build such a class but not meant for use in actual applications.

For PXSourceList 2 I decided that having a class like this that was part of the project and could be used in most applications would be quite useful. To this end, PXSourceList 2 contains a PXSourceListItem class for this purpose, which is based on the implementation of SourceListItem but tidied up and improved. Both example projects have been updated to use PXSourceListItem, so take a look at these and the docs for more information on how to use this class.

Documentation

For PXSourceList 0.x and 1.x, I didn’t include the documented header files in the repository because I thought it would add clutter and make the files harder to read.

However, I have realised that this runs counter to the spirit of an open-source project and in-place documentation works well for people who like to browse the source files themselves without having to go and find the generated documentation. All classes, protocols and members (apart from those in the example projects) now have their documented comments included in the header files in the repository.

PXSourceList 2 also includes a Documentation target in the Xcode project, which — if you have appledoc installed — can be used to generate documentation from source by selecting the target and hitting Cmd-B. See the README for more information.

Going Forward

I’m in a much happier place with PXSourceList now, and will do my best to be more diligent in updating the project as new versions of Cocoa are released.

If you find any problems, please don’t hesitate to file an issue on GitHub, and contributions back to the project are always welcome.

Enjoy using PXSourceList 2!

  1. It looks like there were only around 2,000 Objective-C repos on GitHub back in late-2009 (source) and there are over 100,000 as of the date of writing (source). Pretty astounding, although not surprising.

  2. This was a time where appledoc was still Doxygen-based; it parsed Doxygen’s XML output and turned it into nice, Apple-style documentation. Doxygen was pretty hairy to work with at times, so fortunately appledoc 2 has since been released with its own native parser.

  3. I don’t think I realised quite how risky that was until after I’d finished.

  4. The only backwards-incompatible change that’s been made has been marking -[PXSourceList delegate] and -[PXSourceList dataSource] as unavailable, so if you were using these your project will fail to build. However, as noted in the docs since the first version of PXSourceList, you shouldn’t be using these methods.

  5. Expect a blog post titled WHY I IMPLEMENTED AN NSCELL SUBCLASS IN 2014 very soon.

Want to get in touch? You can find me as @alexrozanski on Twitter.