#PXSourceList

A Source List control for use with the Mac OS X 10.5 SDK or above.

Download the documentation

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:

1. Download the source, and copy PXSourceList.h, PXSourceList.m, PXSourceListDelegate.h and PXSourceListDataSource.h into your Xcode project.
2. 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 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.
3. 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 delegate and/or dataSource for the Source List conform to the PXSourceListDelegate and PXSourceListDataSource 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.

##Screenshots

##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 or dataSource 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.

##License PXSourceList is licensed under the New BSD License, as detailed below (adapted from OSI http://www.opensource.org/licenses/bsd-license.php):

Copyright © 2011, Alex Rozanski. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.