Skip to content
This repository has been archived by the owner on Jan 18, 2023. It is now read-only.

Commit

Permalink
Improve class documentation for PXSourceList.
Browse files Browse the repository at this point in the history
  • Loading branch information
alexrozanski committed Jan 27, 2014
1 parent 1d82dc7 commit 92b64ab
Showing 1 changed file with 10 additions and 11 deletions.
21 changes: 10 additions & 11 deletions PXSourceList/PXSourceList.h
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,10 @@

/**
`PXSourceList` is an `NSOutlineView` subclass that uses 'Source List' styling similar to that used by the
sidebar in applications such as iTunes and Mail.app. It makes implementing Source Lists a lot easier
beyond the standard AppKit "Source List Styling" option and `-outlineView:isGroupItem:` delegate method on
`NSOutlineViewDelegate` by making several assumptions about how "conventional" Source Lists operate:
`PXSourceList` is an `NSOutlineView` subclass that makes using a source list (the sidebar
seen in applications such as iTunes and Mail.app) easier by providing common styling and idiomatic
behaviour of source lists for you through a clean and simple API. Notable features of PXSourceList include:
- `PXSourceList` objects operate with only one column and do not display a header, something
which is reflected in the API and makes the control easier to use.
- All root-level, "group" items are displayed using `NSOutlineView`'s group styling by default and requires no additional setup.
- Source List items often display an *icon* and *badge* (for information such as unread counts). This is built into
the API to make configuring these quick and easy, and a badge `NSControl` subclass is included which can be added to
Expand All @@ -32,6 +29,8 @@
and no 'Show'/'Hide' button is displayed when hovering over the group. This is often useful for listing the main
contexts your application can be in at any given time, which the user can select to change views. As it is paramount to
your application's navigation, these groups are often displayed with their child items always shown.
- `PXSourceList` objects operate with only one column and do not display a header, something
which is reflected in the API and makes the control easier to use.
Like `NSOutlineView` and `NSTableView`, a `PXSourceList` object does not store its own data, but retrieves
values from a weakly-referenced data source (see the `PXSourceListDataSource` protocol). A `PXSourceList`
Expand All @@ -40,11 +39,11 @@
### Cell-based vs. view-based mode
Like `NSTableView` and `NSOutlineView`, `PXSourceList` can operate in both cell-based and view-based mode in
Like `NSTableView` and `NSOutlineView`, PXSourceList can operate in both cell-based and view-based mode in
relation to how you provide content to be displayed.
When using `PXSourceList` in cell-based mode, it can manage drawing of icons and badges for you through custom
drawing and `PXSourceListDataSource` methods. However, when using `PXSourceList` in view-based mode, it can't
When using PXSourceList in cell-based mode, it can manage drawing of icons and badges for you through custom
drawing and `PXSourceListDataSource` methods. However, when using PXSourceList in view-based mode, it can't
do this directly, because cell views are configured independently in Interface Builder (or programmatically)
and configured in the `PXSourceListDataSource` method, `-sourceList:viewForItem:`.
Expand All @@ -64,12 +63,12 @@
### Creating a data source model with `PXSourceListItem`
Like `NSOutlineView`, `PXSourceList` queries its data source to build up a tree-like structure of content using
Like `NSOutlineView`, PXSourceList queries its data source to build up a tree-like structure of content using
`-sourceList:numberOfChildrenOfItem:` and `-sourceList:child:ofItem:`. Often it is practical to store the structure
of your Source List content in a tree structure which can then be easily returned the the Source List using
these two data source methods.
To help with this, the generic `PXSourceListItem` class has been included with `PXSourceList` which can be
To help with this, the generic `PXSourceListItem` class has been included with PXSourceList which can be
used to build this tree structure. It declares properties such as `title` and `icon` which are useful in
storing display information which can then be used in `-sourceList:viewForItem:` or `-sourceList:objectValueForItem:`,
as well as a `children` property with convenience methods for mutating its list of children. Take a look at the
Expand Down

0 comments on commit 92b64ab

Please sign in to comment.