by Alex Rozanski

PXSourceList: Source List Control for Mac OS X

Jan 16th 2010Published in Cocoa, Development

Source Lists feature in many Mac OS X applications. From iTunes to iCal to Versions, they are a great navigation control.

But for us Cocoa developers, they aren’t that easy to implement. You can easily create an NSOutlineView and set its highlight mode to “Source List” but none of the other Source List features come built in out of the box, such as the ability to display badges or icons for items.

PXSourceList Demo

I created PXSourceList to help address this issue. It is a reusable control (within the context of Source Lists) compatible with Mac OS X 10.5 and higher. It makes implementing Source Lists in your applications easier by adding the following main features:

  • Automatic Group highlighting of top-level items – the text for Group items appears in a dark blue colour and is normally displayed as capitalized.
  • Support for Badges – these are dark blue capsules displayed to the right of certain items that display a number.
  • The option to display an Icon for each row – a small image that provides extra visual information for each row.
  • Right-clicking support to display context menus.

Getting the control

The source is available to download from GitHub, or you can clone it straight from the command line:

$ git clone

More Information

More information about PXSourceList is available from the project page.

There is also documentation available – a link to this can be found on the downloads page for the project on GitHub.

If you have any other questions then feel free to get in touch and I’ll be happy to help.

Comments — 15

  1. RightThat'sMyName

    Jan 15, 2011


    I love your PXSourceList. But I’m missing something. There’s nothing like “-(void) sourceList:…didEditItemAtRow”

    Could you at that?? That would be awesome 🙂

    Anyway thank you very much for this. 🙂

  2. Alex Rozanski(Author)

    Jan 15, 2011

    @RightThat’sMyName: Yes, there is a method that does that; it’s

    – (void)sourceList:setObjectValue:forItem:

    declared in the PXSourceListDataSource protocol, much like

    – (void)outlineView:setObjectValue:forTableColumn:byItem:

    declared on NSOutlineView’s NSOutlineViewDataSource protocol. It’s a method which notifies the data source that an item has been edited and it should update its model to reflect these changes.

  3. RightThat’sMyName

    Jan 15, 2011

    ouu…thank you very much for your help ^^ :). It worked.

  4. Tom

    Jan 15, 2011

    Hi Alex,
    I have a question. You can detect that the delete key is pressed on a row.( in the method “sourceListDeleteKeyPressedOnRows”).

    Could you make me an example how to remove the row on that the delete key was pressed? I’m not really familiar with Mac development (and your PXSourceList..but soon) only with iPhone development.


  5. Alex Rozanski(Author)

    Jan 15, 2011

    @Tom: You want to update your model first, to remove the item(s) to be deleted.

    Then call -reloadData on the Source List to update the display; you may also want to change the selection by calling -selectRowIndexes:byExtendingSelection: to either remove the selection or alter it.

  6. Tom

    Jan 16, 2011


    Yes but how can I delete a item at a specific row? I don’t really know how to delete an item itself.


  7. Alex Rozanski(Author)

    Jan 16, 2011

    @Tom: That entirely depends on how your data model is constructed. The aim of the notification is to allow you to delete an item (if it can be deleted). This is done by removing it from your data model, and then calling -reloadData on the Source List to tell it that your data has changed. You can work out which row(s) are currently selected from the Notification object’s userInfo dictionary, which has the selected indexes stored under the key @”rows”, and this can be converted to the item to be deleted by calling -itemForRow: on the Source List.

  8. Tom

    Jan 16, 2011


    Thank you very much for you help. I understand it now 🙂

  9. Knightlie

    Sep 23, 2011

    Hi Alex,

    Thank you for this control, it’s awesome. The only problem I have is that the – (void)sourceList:setObjectValue:forItem: method of my data source isn’t being called. As far as I can tell outlineView:setObjectValue:forItem: in PXSourceList isn’t being called either.

    Is there anything I need to do other than set the data source and delegate? I’m using the SourceListItem code in my data source.

  10. Knightlie

    Sep 24, 2011

    Me again, I fixed it!

  11. kdeda

    Jan 31, 2012

    setAutosaveExpandedItems: is not triggering the itemForPersistentObject:
    i see support on the code, i am missing something?

  12. kdeda

    Jan 31, 2012


    you have to set the autosave as well for this to kick in.

    [sourceList setAutosaveExpandedItems:YES];
    [sourceList setAutosaveName:@”TEST1″];

  13. murugha

    May 7, 2013

    how to expand the group by clicking the group row

  14. Andy

    May 16, 2013


    I have used your control and its awesome. Now I have a small problem, I want to create an application like iTunes, which has dragabble nsoutlineview. Can we do this here.
    Any help would be greatly appreciable.

  15. AndyN

    Feb 13, 2014

    Thanks so much for this!!!

    I was pulling my hair out trying to get icons into NSOutlineView.

Add comment

Please enter your name and comment