From 05e69c85c7cbb542edd2457fe24df395736ea98b Mon Sep 17 00:00:00 2001 From: Randall Luecke Date: Wed, 12 Jan 2011 23:40:28 -0500 Subject: [PATCH] More documentation of the tableview, outlineview, and table columns. Wrapped formatted documenation in 
 tags and added sample code
 for using custom dataviews

---
 AppKit/CPOutlineView.j |  6 ++++-
 AppKit/CPTableColumn.j | 56 ++++++++++++++++++++++++++++++++++++------
 AppKit/CPTableView.j   | 22 ++++++++++++++---
 3 files changed, 72 insertions(+), 12 deletions(-)

diff --git a/AppKit/CPOutlineView.j b/AppKit/CPOutlineView.j
index f27952646..886c495f1 100644
--- a/AppKit/CPOutlineView.j
+++ b/AppKit/CPOutlineView.j
@@ -84,6 +84,7 @@ CPOutlineViewDropOnItemIndex = -1;
 
     Like the tableview, an outlineview uses a data source to supply its data. For this reason you must implement a couple data source methods (documented in setDataSource:)
 
+    Theme states for custom data views are documented in CPTableView
 */
 @implementation CPOutlineView : CPTableView
 {
@@ -150,6 +151,7 @@ CPOutlineViewDropOnItemIndex = -1;
     return self;
 }
 /*!
+
     In addition to standard delegation, the outline view also supports data source delegation. This method sets the data source object.
     Just like the TableView you have CPTableColumns but instead of rows you deal with items.
 
@@ -195,7 +197,7 @@ CPOutlineViewDropOnItemIndex = -1;
         Returns YES if the drop operation is allowed otherwise NO.
         This method is invoked by the outlineview after a drag should begin, but before it is started. If you dont want the drag to being return NO.
         If you want the drag to begin you should return YES and place the drag data on the pboard.
-
+

 */
 - (void)setDataSource:(id)aDataSource
 {
@@ -667,6 +669,7 @@ CPOutlineViewDropOnItemIndex = -1;
 }
 
 /*!
+
     Sets the delegate for the outlineview.
 
     The following methods can be implemented:
@@ -727,6 +730,7 @@ CPOutlineViewDropOnItemIndex = -1;
         Return YES if the item is a group item, otherwise NO.
 
     @param aDelegate - the delegate object you wish to set for the reciever.
+
 */
 - (void)setDelegate:(id)aDelegate
 {
diff --git a/AppKit/CPTableColumn.j b/AppKit/CPTableColumn.j
index ba79f9c3f..2054a9cd7 100644
--- a/AppKit/CPTableColumn.j
+++ b/AppKit/CPTableColumn.j
@@ -39,7 +39,7 @@ CPTableColumnUserResizingMask   = 1 << 1;
     A CPTableColumn contains a dataview to display for its column of the CPTableView.
     A CPTableColumn determines its own size constrains and resizing behaviour.
 
-    The default dataview is a CPTextField but you can set it to any view you'd like. See -setDataView:
+    The default dataview is a CPTextField but you can set it to any view you'd like. See -setDataView: for documentaion including theme states.
 */
 @implementation CPTableColumn : CPObject
 {
@@ -253,6 +253,7 @@ CPTableColumnUserResizingMask   = 1 << 1;
 }
 
 /*!
+
     Set the resizing mask of the column. 
     By default the column can be resized automatically with the tableview and manaully by the user
 
@@ -260,6 +261,7 @@ CPTableColumnUserResizingMask   = 1 << 1;
     CPTableColumnNoResizing
     CPTableColumnAutoresizingMask
     CPTableColumnUserResizingMask
+

 */
 - (void)setResizingMask:(unsigned)aResizingMask
 {
@@ -318,11 +320,19 @@ CPTableColumnUserResizingMask   = 1 << 1;
 }
 
 /*!
+
     This method sets the "prototype" view which will be used to create all table cells in this column.
 
     It creates a snapshot of aView, using keyed archiving, which is then copied over and over for each
     individual cell that is shown. As a result, changes made after calling this method won't be reflected.
 
+    When you set a dataview and it is added to the tableview the theme state will be set to CPThemeStateTableDataView
+    When the dataview becomes selected the theme state will be set to CPThemeStateSelectedDataView.
+
+    If the dataview shows up in a group row of the tablview the theme state will be set to CPThemeStateGroupRow.
+
+    You should overide setThemeState: and unsetThemeState: to handle these theme state changes in your dataview.
+
     Example:
 
         [tableColumn setDataView:someView]; // snapshot taken
@@ -333,7 +343,37 @@ CPTableColumnUserResizingMask   = 1 << 1;
         [someView setSomething:x];
         [tableColumn setDataView:someView];
 
-    REMEMBER: you should implement CPKeyedArchiving otherwise you might see unexpected results
+    REMEMBER: you should implement CPKeyedArchiving otherwise you might see unexpected results.
+    This is done by adding the following methods to your class:
+    - (id)initWithCoder(CPCoder)aCoder;
+    - (void)encodeWithCoder:(CPCoder)aCoder;
+
+    Example:
+    Say you have two instance variables in your object that need to be set up each time an object is create.
+    We will call these instance variables "image" and "text".
+    Your CPCoding methods will look like the following:
+
+    - (id)initWithCoder:(CPCoder)aCoder
+    {
+        self = [super initWithCoder:aCoder];
+
+        if (self)
+        {
+            image = [aCoder decodeObjectForKey:"MyDataViewImage"];
+            text = [aCoder decodeObjectForKey:"MyDataViewText"];
+        }
+
+        return self;
+    }
+
+    - (void)encodeWithCoder:(CPCoder)aCoder
+    {
+        [super encodeWithCoder:aCoder];
+
+        [aCoder encodeObject:image forKey:"MyDataViewImage"];
+        [aCoder encodeObject:text forKey:"MyDataViewText"];
+    }
+

 */
 - (void)setDataView:(CPView)aView
 {
@@ -355,7 +395,7 @@ CPTableColumnUserResizingMask   = 1 << 1;
     Returns the CPView object used by the CPTableView to draw values for the receiver.
 
     By default, this method just calls dataView. Subclassers can override if they need to
-    potentially use different cells for different rows. Subclasses should expect this method
+    potentially use different "cells" or dataViews for different rows. Subclasses should expect this method
     to be invoked with row equal to -1 in cases where no actual row is involved but the table
     view needs to get some generic cell info.
 */
@@ -392,7 +432,7 @@ CPTableColumnUserResizingMask   = 1 << 1;
 
 //Setting the Identifier
 
-/*
+/*!
     Sets the receiver identifier to anIdentifier.
 */
 - (void)setIdentifier:(id)anIdentifier
@@ -400,7 +440,7 @@ CPTableColumnUserResizingMask   = 1 << 1;
     _identifier = anIdentifier;
 }
 
-/*
+/*!
     Returns the object used by the data source to identify the attribute corresponding to the receiver.
 */
 - (id)identifier
@@ -410,7 +450,7 @@ CPTableColumnUserResizingMask   = 1 << 1;
 
 //Controlling Editability
 
-/*
+/*!
     Controls whether the user can edit cells in the receiver by double-clicking them.
 */
 - (void)setEditable:(BOOL)shouldBeEditable
@@ -418,7 +458,7 @@ CPTableColumnUserResizingMask   = 1 << 1;
     _isEditable = shouldBeEditable;
 }
 
-/*
+/*!
     Returns YES if the user can edit cells associated with the receiver by double-clicking the
     column in the NSTableView, NO otherwise.
 */
@@ -469,7 +509,7 @@ CPTableColumnUserResizingMask   = 1 << 1;
 
 //Setting Tool Tips
 
-/*
+/*!
     Sets the tooltip string that is displayed when the cursor pauses over the
     header cell of the receiver.
 */
diff --git a/AppKit/CPTableView.j b/AppKit/CPTableView.j
index cc051ffcd..a0a456b6c 100644
--- a/AppKit/CPTableView.j
+++ b/AppKit/CPTableView.j
@@ -147,7 +147,7 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 
     All delegate and data source methods are documented in the setDataSource: and setDelegate: methods.
 
-    If you want to display something other than just text in the table you should call setDataView: on CPColumn. More documentation in that class.
+    If you want to display something other than just text in the table you should call setDataView: on a CPColumn object. More documentation in that class including theme states.
 */
 @implementation CPTableView : CPControl
 {
@@ -378,6 +378,7 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 }
 
 /*!
+
     Sets the receiver's data source to a given object.
     The data source implements various methods for handeling the tableview's data when bindings are not used.
 
@@ -416,7 +417,7 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 
     - (CPArray)tableView:(CPTableView)aTableView namesOfPromisedFilesDroppedAtDestination:(CPURL)dropDestination forDraggedRowsWithIndexes:(CPIndexSet)indexSet;
         NOT YET IMPLEMENTED
-
+

     @param anObject The data source for the receiver. This object must implement numberOfRowsInTableView: and tableView:objectValueForTableColumn:row:
 */
 - (void)setDataSource:(id)aDataSource
@@ -722,11 +723,13 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 
 /*!
     Returns an enumerated value for the selection highlight style.
+
 
     Valid values are:
         CPTableViewSelectionHighlightStyleNone
         CPTableViewSelectionHighlightStyleRegular
         CPTableViewSelectionHighlightStyleSourceList
+

 */
 - (unsigned)selectionHighlightStyle
 {
@@ -734,6 +737,7 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 }
 
 /*!
+
     Sets the selection highlight style to an enumerated value.
     This value can also affect the way the tableview draws feedback when the user is dragging.
 
@@ -741,6 +745,7 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
         CPTableViewSelectionHighlightStyleNone
         CPTableViewSelectionHighlightStyleRegular
         CPTableViewSelectionHighlightStyleSourceList
+

 */
 - (void)setSelectionHighlightStyle:(unsigned)aSelectionHighlightStyle
 {
@@ -778,12 +783,14 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 }
 
 /*!
+
     Sets the highlight gradient for a row or column selection
     This is specific to the
     @param aDictionary a CPDictionary expects three keys to be set:
         CPSourceListGradient which is a CGGradient
         CPSourceListTopLineColor which is a CPColor
         CPSourceListBottomLineColor which is a CPColor
+

 */
 - (void)setSelectionGradientColors:(CPDictionary)aDictionary
 {
@@ -793,10 +800,12 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 }
 
 /*!
+
     Returns a dictionary of containing the keys:
     CPSourceListGradient
     CPSourceListTopLineColor
     CPSourceListBottomLineColor
+

 */
 - (CPDictionary)selectionGradientColors
 {
@@ -1927,6 +1936,7 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 }
 
 /*!
+
     Sets the column autoresizing style of the receiver to a given style.
 
     @param aStyle the column autoresizing style for the receiver. Valid values are:
@@ -1934,6 +1944,7 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
         CPTableViewUniformColumnAutoresizingStyle
         CPTableViewLastColumnOnlyAutoresizingStyle
         CPTableViewFirstColumnOnlyAutoresizingStyle
+

 */
 - (void)setColumnAutoresizingStyle:(unsigned)style
 {
@@ -2237,6 +2248,7 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 
 
 /*!
+
     Sets the delegate of the receiver. The delegate can implement the following methods:
     Displaying Cells
     - (void)tableView:(CPTableView)aTableView willDisplayView:(id)aView forTableColumn:(CPTableColumn)aTableColumn row:(int)rowIndex;
@@ -2302,7 +2314,7 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
     - (CPMenu)tableView:(CPTableView)aTableView menuForTableColumn:(CPTableColumn)aColumn row:(int)aRow
         Called when the user right clicks on the tableview. -1 is passed for the row or column if the user doesn't right click on a real row or column
         Return a CPMenu that should be displayed if the user right clicks. If you do not implement this the tableview will just call super on menuForEvent
-
+

     @param aDelegate the delegate object for the tableview.
 
 */
@@ -2782,11 +2794,13 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 }
 
 /*!
+
     Sets the feedback style for when the table is the destination of a drag operation.
     Can be:
         CPTableViewDraggingDestinationFeedbackStyleNone
         CPTableViewDraggingDestinationFeedbackStyleRegular
         CPTableViewDraggingDestinationFeedbackStyleSourceList
+

 */
 - (void)setDraggingDestinationFeedbackStyle:(CPTableViewDraggingDestinationFeedbackStyle)aStyle
 {
@@ -2795,12 +2809,14 @@ CPTableViewFirstColumnOnlyAutoresizingStyle = 5;
 }
 
 /*!
+
     Returns the tableview dragging destination feedback style.
 
     Can be:
         CPTableViewDraggingDestinationFeedbackStyleNone
         CPTableViewDraggingDestinationFeedbackStyleRegular
         CPTableViewDraggingDestinationFeedbackStyleSourceList
+

 */
 - (CPTableViewDraggingDestinationFeedbackStyle)draggingDestinationFeedbackStyle
 {