From 92b64abde545b28a422d3fe0555ba8d370917b05 Mon Sep 17 00:00:00 2001 From: Alex Rozanski Date: Mon, 27 Jan 2014 17:37:23 +0000 Subject: [PATCH] Improve class documentation for PXSourceList. --- PXSourceList/PXSourceList.h | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/PXSourceList/PXSourceList.h b/PXSourceList/PXSourceList.h index 20ec289..00b1032 100644 --- a/PXSourceList/PXSourceList.h +++ b/PXSourceList/PXSourceList.h @@ -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 @@ -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` @@ -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:`. @@ -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