PXSourceList is an
NSOutlineView subclass used for easily implementing source lists in your applications.
PXSourceList requires the OS X 10.7 SDK and above and is licensed under the New BSD License.
Using a source list for navigation is a common user interface paradigm in OS X applications, but requires a fair amount of manual set up and customisation of standard Cocoa controls.
PXSourceList subclasses NSOutlineView and provides much of the common styling and idiomatic behaviour of source lists for you through a clean and simple API.
PXSourceList has several key features:
- Built-in support for displaying badges — blue-grey pills which display numerical values such as the number of photos in a particular album.
- Always displaying root-level items with ‘group styling’ — the blue-grey uppercase text seen in the source lists in apps such as Mail.app. This requires no extra configuration.
- Support for displaying specific groups as ‘always expanded’ through implementation of a single delegate method. These groups will always show their child items and won’t show a Show/Hide button on hover.
- Since idiomatic source lists use only a single column and don’t display column headers, PXSourceList operates with only a single table column and doesn’t display a header. This is reflected in PXSourceList’s API and makes the control easier to use.
- The project includes a generic data model class which can be used for building a data source data model without having to roll your own.
Note that in the OS X Human Interface Guidelines, source lists are broken down into those which provide navigation for the app as a whole (and have a blue-grey background), and those which provide selection functionality for the window (with a white background). PXSourceList implements this first style of source list; the second type doesn’t require quite as much common customisation so would not be useful as a standalone control.
Installing with CocoaPods
You can install PXSourceList by adding the following line to your
pod 'PXSourceList', '~> 2.0'
Cloning with git
You can also get the source by cloning with git:
$ git clone https://github.com/Perspx/PXSourceList.git
You can then either:
- Copy all of the files from the
PXSourceListdirectory (including those in the
Internalsubdirectory) into your project
- Add the Xcode project as a subproject to your own Xcode project or to your workspace and link against the
Using PXSourceList in your application
- Drag an
NSOutlineViewobject into the window/view that you're displaying the source list in. Often source lists are placed in the leftmost panel of an
- In the Identity inspector for the outline view, change the class from the
- With the source list selected (it helps to use Interface Builder’s Document Outline view for this), select "Source List" for the "Highlight" attribute under the "Table View" section in the Attributes inspector.
- Control-click on the Source List and drag connectors to the object(s) that you want to be your Source List's delegate and data source, selecting "delegate" or "dataSource" respectively from the popup menu that is shown when you release the mouse button. A Source List requires a data source object, but having a delegate is optional.
- 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 source list delegate and data source class(es) conform to the
There are also two example projects included in the project to see how PXSourceList should be used.
Cell-based vs. View-based mode
NSOutlineView subclass, PXSourceList can display its contents using cells (in cell-based mode) or views (in view-based mode). Some delegate and data source methods (see below) are only applicable when PXSourceList is used in cell-based mode, and is noted as such in the documentation.
PXSourceList and its related classes and protocols are documented in the header files included in the repository using appledoc-style documentation.
Documentation (in HTML and docset formats) can be generated by building the Documentation target from the Xcode project. The resulting documentation will be placed in
docs in the root directory of the project. To generate documentation in this way, appledoc must be installed and the script which builds the documentation expects it to be installed under
If you notice any mistakes or feel that any areas of the documentation are lacking or missing, please file a GitHub issue.
PXSourceList 2 is a great improvement over PXSourceList 0.x and 1.x that adds view-based table support and many other small improvements and bugfixes.
For view-based table support, new delegate and data source methods have been added to bring PXSourceList on-par with
NSOutlineView’s API, and a generic badge view and
NSTableCellView subclass have been implemented to allow easy setup of
NSTableCellViews with PXSourceList.
Additionally, a generic
PXSourceListItem class has been implemented for building a data source model without having to roll your own class. A new internal implementation of PXSourceList fixes problems in prior versions where some source list delegate and data source methods weren’t being called.
Take a look at the Release Notes for a comprehensive list of changes as well as API changes in version 2.
Delegate and Data Source Objects
PXSourceList objects obtain their content and other information from their data source and delegate objects using methods defined in the
PXSourceListDelegate protocols respectively.
As well as declaring new delegate and data source methods, since
PXSourceListDelegate include most
NSOutlineViewDataSource methods but with the "outlineView" prefix replaced with "sourceList". For more information on implementing a data source object, take a look at Outline View Programming Topics — PXSourceList’s delegate and data source implementation works in a very similar way.
Note that some of the
NSOutlineView delegate and data source methods are not relevant to PXSourceList, so they haven't been added to
Note also that because of the way PXSourceList works under the hood,
-[PXSourceList delegate] and
-[PXSourceList dataSource] have been marked as unavailable (they return an internal proxy object). You should therefore only use
A PXSourceList data source must implement the following methods:
- (NSUInteger)sourceList:(PXSourceList*)sourceList numberOfChildrenOfItem:(id)item - (id)sourceList:(PXSourceList*)aSourceList child:(NSUInteger)index ofItem:(id)item - (BOOL)sourceList:(PXSourceList*)aSourceList isItemExpandable:(id)item
If you are using PXSourceList in cell-based mode, you also need to implement:
- (id)sourceList:(PXSourceList*)aSourceList objectValueForItem:(id)item
If you are using PXSourceList in view-based mode, you should implement:
- (NSView *)sourceList:(PXSourceList *)aSourceList viewForItem:(id)item
in your delegate object class.
Take a look at both the view-based and cell-based example projects in the repository for more information about implementing PXSourceList delegate and data source objects.
View-Based Source Lists
As mentioned above, PXSourceList can be used in either cell-based- or view-based mode to display content using cells or views.
When using PXSourceList in view-based mode, several classes have been included in the project to help with setting up views for each item in the table, which is done in the
This is a view class that draws a badge with a given numeric value. Badges are displayed to the right of rows that show them and are displayed with a grey-blue background when the row containing them is not selected, or a white background otherwise.
This is an
NSTableCellView subclass that exposes a
badgeView outlet that can be hooked up to a
PXSourceListBadgeView instance in Interface Builder and can then be configured in
-sourceList:viewForItem:. Like with
PXSourceListTableCellView positions its
badgeView automatically for you.
Data Source Model Using PXSourceListItem
PXSourceListItem class has been added in PXSourceList 2 for creation of a data source model without having to roll your own classes.
PXSourceListDataSource works by building up a tree structure of model objects (which maps to the tree-like presentation of the content),
PXSourceListItem allows you to build up a tree structure of model objects using the
children property and other convenience methods.
Each item can have associated with it:
- A title. Useful for setting the
textFieldproperty of an
- An icon image. Useful for setting the image on the
imageViewproperty of an
- An identifier. Useful for identifying a given item when given one as the return value from
PXSourceListmethod or as a parameter to a
- A badge value. Useful to store the badge value for a particular item if it doesn’t have a backing data model object that you pull this value from.
Additionally, each item has a
representedObject property associated with it which is useful when you don’t want to set the data on a source list item directly, but instead want to pull it from an associated model object. This means that you don’t have to keep your data model and properties on
PXSourceListItem in sync.
Thanks first of all to the wonderful people who have contributed to the project and helped in improving the project, fixing bugs and adding new features.
In the initial release of PXSourceList, 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.
Brian Dunagan's post on Source List badging and determining state for the various colours was also a great help when I came to the drawing code for source list badges.
The Documentation target in the Xcode project makes use of the fantastic appledoc, which has been an invaluable tool utilised since the very first version of PXSourceList.
The icons used in the example projects bundled with the source code are from the Fugue icon set by Yusuke Kamiyamane (in the cell-based example) and the Mimi Glyphs set by Jeremy Salée (in the view-based example).
PXSourceList is licensed under the New BSD License, as detailed below (adapted from OSI http://www.opensource.org/licenses/bsd-license.php):
Copyright © 2009-14, Alex Rozanski and other contributors. 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.