#PXSourceList
A Source List control for use with the Mac OS X 10.5 SDK or above.
PXSourceList
is licensed under the New BSD License.
##Intention
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
PXSourceList.h
,PXSourceList.m
,PXSourceListDelegate.h
andPXSourceListDataSource.h
into your Xcode project. - To create the control in Interface Builder, drag an
NSOutlineView
object over to a window and in the Identity Inspector for the Outline View, change the class toPXSourceList
. 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 thedelegate
and/ordataSource
for the Source List conform to thePXSourceListDelegate
andPXSourceListDataSource
protocols respectively.
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 NSOutlineViewDelegate
and NSOutlineViewDataSource
, much in the way that these extend the appropriate NSTableView
protocols.
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 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 For the latest documentation see the PXSourceList downloads page.
##Known Issues
- Calling
delegate
ordataSource
on 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).
##Attribution
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 documentation was created using Doxygen and appledoc, thanks of which go to the developers of both.
The icons used in the demo project bundled with the source code are from the Fugue icon set by Yusuke Kamiyamane.