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!
- 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,
PXSourceListItemdata 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!
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.
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
NSOutlineView back in Lion). Extra delegate methods have been added to
-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:
NSControlsubclass which draws badges. Its backing cell5 is used when
PXSourceListis configured in cell-based mode, but it can also be used in
NSTableCellViews when using
PXSourceListin view-based mode to draw badges with the idiomatic white-on-grey-blue Source List badge colours.
NSTableCellViewsubclass which includes a
badgeViewoutlet for connecting up a
PXSourceListBadgeViewobject in Interface Builder. Along with
imageViewproperties, 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
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
PXSourceListTableCellView will lay out the
badgeView for you at a default position in
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
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.
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.
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!
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. ↩
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. ↩
I don’t think I realised quite how risky that was until after I’d finished. ↩
The only backwards-incompatible change that’s been made has been marking
-[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. ↩
Expect a blog post titled WHY I IMPLEMENTED AN NSCELL SUBCLASS IN 2014 very soon. ↩