<commit_before>#PXSourceList

`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.

![PXSourceList in action: The view-based example project included in the repository.](https://raw.github.com/Perspx/PXSourceList/master/Examples/Screenshots/PXSourceList-ViewBased-Example.png)

## Motivation
[Source Lists][2] are used in a lot of OS X applications, but the support for such controls is quite primitive – at best Cocoa allows you to create an outline view with Source List-style highlighting, but none of the features common to idiomatic Source Lists such as badging, and all top-level items being displayed differently are built in by default.

`PXSourceList` implements lots of this idiomatic behaviour for you, which makes adding a Source List to your applications a lot easier and quicker.

## Using `PXSourceList`

### Getting the code

Clone the repository:

    $ git clone https://github.com/Perspx/PXSourceList.git

You can then either:

  * Copy all of the files from the `PXSourceList` directory (including those in the `Internal` subdirectory) into your project.
  * **or** add the Xcode project as a subproject to your own Xcode project, or to your workspace and link against the PXSourceList framework target.

### Adding `PXSourceList` to your application

 1. Drag an `NSOutlineView` object into the window/view that you're displaying the Source List in.
 2. In the Identity inspector for the outline view, change the class from the default (`NSOutlineView`) to `PXSourceList`.
 3. With the *Source List* selected, select "Source List" for the "Highlight" attribute in the Attributes inspector under the "Table View" section.
 4. 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.
 5. 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.

There are also two example projects bundled with the source to see how `PXSourceList` should be used.

## Delegate and Data Source
`PXSourceList` adopts the delegation pattern by using two protocols: `PXSourceListDataSource` and `PXSourceListDelegate`. These protocols include most `NSOutlineView` delegate and data source methods, but with the "outlineView" prefix replaced with "sourceList". Some of the `NSOutlineView` delegate and data source methods haven't been carried over or their method signature has been modified slightly because they don't make sense in the context of `PXSourceList`, since it works with only a single table column and no column headers.

If you want more information have a look at *[Outline View Programming Topics for Cocoa][4]* – the Source List delegate and data source implementation work in a very similar way.

Note that because of the way `PXSourceList` works under the hood, `-[PXSourceList delegate]` and `-[PXSourceList dataSource]` have been marked as unavailable as they return an internal proxy object. You should therefore only use `-setDelegate:` and `-setDataSource:`.

##Documentation
`PXSourceList` and its related classes and protocols are documented in the header files included in the repository using [appledoc](http://gentlebytes.com/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. Note that appledoc has to be installed and the script which builds the documentation expects it to be under `/usr/local/bin`.

If you notice any mistakes or feel that any areas of the documentation are lacking or missing, please file a GitHub issue.

##Attribution

I was spurred along the way by many sources, but in particular [BWToolkit][8] by <NAME> and <NAME>, which gave me the idea of how to handle the Source List delegate and data source methods.

Also <NAME>'s post on [Source List badging][9] 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][10] and [appledoc][11], thanks of which go to the developers of both.

The icons used in the example projects bundled with the source code are from the [Fugue icon set][12] by <NAME> and the [Mimi Glyphs set][13] by <NAME>.

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


Copyright &copy; 2011, <NAME>.
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.


  [1]: http://github.com/Perspx/PXSourceList/downloads
  [2]: http://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/AppleHIGuidelines/Windows/Windows.html#//apple_ref/doc/uid/20000961-CHDDIGDE
  [3]: http://perspx.com/wp-content/uploads/2010/01/pxsourcelist.jpg
  [4]: http://developer.apple.com/mac/library/DOCUMENTATION/Cocoa/Conceptual/OutlineView/Articles/UsingOutlineDataSource.html
  [5]: http://github.com/Perspx/PXSourceList/downloads
  [6]: http://perspx.com/contact
  [7]: http://github.com/Perspx/PXSourceList/downloads
  [8]: http://brandonwalkin.com/bwtoolkit/
  [9]: http://www.bdunagan.com/2008/11/10/cocoa-tutorial-source-list-badges-part-2/
  [10]: http://www.doxygen.org/
  [11]: http://www.gentlebytes.com/freeware/appledoc/
  [12]: http://www.pinvoke.com/
  [13]: http://salleedesign.com/resources/mimi-glyphs/
<commit_msg>Grammar :|<commit_after>#PXSourceList

`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.

![PXSourceList in action: The view-based example project included in the repository.](https://raw.github.com/Perspx/PXSourceList/master/Examples/Screenshots/PXSourceList-ViewBased-Example.png)

## Motivation
[Source Lists][2] are used in a lot of OS X applications, but the support for such controls is quite primitive – at best Cocoa allows you to create an outline view with Source List-style highlighting, but none of the features common to idiomatic Source Lists such as badging, and all top-level items being displayed differently are built in by default.

`PXSourceList` implements lots of this idiomatic behaviour for you, which makes adding a Source List to your applications a lot easier and quicker.

## Using `PXSourceList`

### Getting the code

Clone the repository:

    $ git clone https://github.com/Perspx/PXSourceList.git

You can then either:

  * Copy all of the files from the `PXSourceList` directory (including those in the `Internal` subdirectory) into your project.
  * **or** add the Xcode project as a subproject to your own Xcode project, or to your workspace and link against the PXSourceList framework target.

### Adding `PXSourceList` to your application

 1. Drag an `NSOutlineView` object into the window/view that you're displaying the Source List in.
 2. In the Identity inspector for the outline view, change the class from the default (`NSOutlineView`) to `PXSourceList`.
 3. With the *Source List* selected, select "Source List" for the "Highlight" attribute in the Attributes inspector under the "Table View" section.
 4. 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.
 5. 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.

There are also two example projects bundled with the source to see how `PXSourceList` should be used.

## Delegate and Data Source
`PXSourceList` adopts the delegation pattern by using two protocols: `PXSourceListDataSource` and `PXSourceListDelegate`. These protocols include most `NSOutlineView` delegate and data source methods, but with the "outlineView" prefix replaced with "sourceList". Some of the `NSOutlineView` delegate and data source methods haven't been carried over or their method signature has been modified slightly because they don't make sense in the context of `PXSourceList`, since it works with only a single table column and no column headers.

If you want more information have a look at *[Outline View Programming Topics for Cocoa][4]* – the Source List delegate and data source implementation work in a very similar way.

Note that because of the way `PXSourceList` works under the hood, `-[PXSourceList delegate]` and `-[PXSourceList dataSource]` have been marked as unavailable as they return an internal proxy object. You should therefore only use `-setDelegate:` and `-setDataSource:`.

##Documentation
`PXSourceList` and its related classes and protocols are documented in the header files included in the repository using [appledoc](http://gentlebytes.com/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. Note that appledoc has to be installed and the script which builds the documentation expects it to be under `/usr/local/bin`.

If you notice any mistakes or feel that any areas of the documentation are lacking or missing, please file a GitHub issue.

##Attribution

I was spurred along the way by many sources, but in particular [BWToolkit][8] by <NAME> and <NAME>, which gave me the idea of how to handle the Source List delegate and data source methods.

Also <NAME>'s post on [Source List badging][9] 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][10] and [appledoc][11], thanks of which go to the developers of both.

The icons used in the example projects bundled with the source code are from the [Fugue icon set][12] by <NAME> and the [Mimi Glyphs set][13] by <NAME>.

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


Copyright &copy; 2011, <NAME>.
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.


  [1]: http://github.com/Perspx/PXSourceList/downloads
  [2]: http://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/AppleHIGuidelines/Windows/Windows.html#//apple_ref/doc/uid/20000961-CHDDIGDE
  [3]: http://perspx.com/wp-content/uploads/2010/01/pxsourcelist.jpg
  [4]: http://developer.apple.com/mac/library/DOCUMENTATION/Cocoa/Conceptual/OutlineView/Articles/UsingOutlineDataSource.html
  [5]: http://github.com/Perspx/PXSourceList/downloads
  [6]: http://perspx.com/contact
  [7]: http://github.com/Perspx/PXSourceList/downloads
  [8]: http://brandonwalkin.com/bwtoolkit/
  [9]: http://www.bdunagan.com/2008/11/10/cocoa-tutorial-source-list-badges-part-2/
  [10]: http://www.doxygen.org/
  [11]: http://www.gentlebytes.com/freeware/appledoc/
  [12]: http://www.pinvoke.com/
  [13]: http://salleedesign.com/resources/mimi-glyphs/

{'fraction_non_alphanumeric': 0.06900759219088937, 'fraction_numerical': 0.008676789587852495, 'mean_word_length': 4.8660039761431415, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 4, 'lorem ipsum': 0, 'www.': 10, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6909959', 'n_tokens_mistral': 4036, 'n_tokens_neox': 3742, 'n_words': 1943}