A Source List control for use with the Mac OS X 10.5 SDK or above.
PXSourceList is licensed under the New BSD License.
Source Lists are used in a lot of Mac OS X applications, but the support for such controls is quite primitive – at best you create an Outline View with Source List highlighting, but none of the features such as badging are built in by default.
PXSourceList is a reusable control – within the context of Source Lists – which makes creating applications with Source Lists a much easier process.
Using the code
There are only a few steps involved:
- Download the source, and copy
PXSourceListDataSource.hinto your Xcode project.
- To create the control in Interface Builder, drag an
NSOutlineViewobject over to a window and in the Identity Inspector for the Outline View, change the class to
PXSourceList. In the Attributes Inspector, set it to have only 1 column, uncheck "Headers" in the "Columns" section and set "Highlight" to "Source List" – there is an NIB in the example project bundled with the source.
- Make sure to
#import "PXSourceList.h"for files that require it (the delegate and data source protocol files are imported in this main header), and ensure that your class(es) that are the
dataSourcefor the Source List conform to the
Note: If you intend to use PXSourceList with the 10.5 SDK, you will need to remove some of the protocols that PXSourceList conforms to which do not exist – in
PXSourceList.h, remove the
<NSOutlineViewDelegate, NSOutlineViewDataSource, NSMenuDelegate> from the interface declaration.
There is also an example project bundled with the source to see how the control is used.
How the control works
I have tried to structure PXSourceList in a way such that it fits common Cocoa design patterns and therefore makes it easier to use.
PXSourceList adapts the delegate and data source design patterns, and extends those of the
NSOutlineViewDataSource, much in the way that these extend the appropriate
If you want more information have a look at the Outline View Programming Topics for Cocoa – the Source List delegate and data source implementation work in much the same way, but with methods added and removed, as detailed in the documentation.
Documentation is available for PXSourceList, downloadable here. Provided in the ZIP file is a folder containing HTML documentation, or a docset which can be opened in Xcode and which is then searchable from the Xcode Developer Documentation.
If you feel that any areas of the documentation are lacking or missing, please feel free to let me know, which will be much appreciated.
Note: the documentation for the Source List notifications can be found in the
NSObject(PXSourceListNotifications) reference, which is linked to from the documentation index page.
Documentation Revision History
dataSourceon the Source List returns the Source List instance. This is, unfortunately, a side effect of how delegate and data source methods are handled within the Source List – I hope to work around it in the future.
- No bindings implementation (yet).
I was spurred along the way by many sources, but in particular BWToolkit by Brandon Walkin and Fraser Kuyvenhoven, which gave me the idea of how to handle the Source List delegate and data source methods.
Also Brian Dunagan's post on Source List badging and determining state for the various colours was a great help when I came to the drawing code for that.
The icons used in the demo project bundled with the source code are from the Fugue icon set by Yusuke Kamiyamane.