CPTableView: A Ponderings and Guesses Regarding Delegate Functions

This originally was part of the CPTableView Part 4 tutorial.  But it was so long and unwieldy, I have decided to break it off as a stub.  At first, it was just a list of functions, but as I review the code and learn more about each function, I will list my assumptions and learned behaviors here.

Keep in mind, delegates and data sources are different!  It does appear as though a delegate can be used instead of a data source, because the data source functions are called on the delegate as well.  At this time, I do not know if the delegate is called in addition to the data source or instead of the data source, or if both are called, in what order they are accessed, but these are things that are easy enough to test if you absolutely need to know.  At this time in our Cappuccino education, this information is considered to be too in-depth to aid in our general understanding of how to work around the concept.

Delegate Functions

Delegates give us an opportunity to change the behavior of objects to which they are associated. The object first tests a delegate to determine if it has a specified method. But to take advantage of these functions, we must know which functions are tested and called. We already know that delegate functions in Cappuccino and Cocoa are sometimes different, so we will review the Cappuccino code to get our answers.

Digging through the code of CPTableView.j, we find the following:

Passed to an attribute called defaultCenter

These function calls and have an unknown format.  We assume that these functions return no value and are passed an instance of the table view:

1. tableViewColumnDidMove:
2. tableViewColumnDidResize:
3. tableViewSelectionDidChange:
4. tableViewSelectionIsChanging:

Called by CPTableView directly:

Functions that are known

Informational functions that require no response or data for processing are listed here.  These functions just give the delegate information and a chance to do additional processing or actions when the events occur:

-(void)tableView:(CPTableView)aTable didDragTableColumn:(CPTableColumn)draggedColumn

-(void)tableView:(CPTableView)aTable mouseDownInHeaderOfTableColumn:(CPTableColumn)clickedColumn

-(void)tableView:(CPTableView)aTable willDisplayView:(id)aCell forTableColumn:(CPTableColumn)aColumn row:(CPInteger)aRowIndex

The last one, willDisplayView, seems to give the delegate a chance to modify views that are provided by the data source before they are displayed.... We are going to play with that a bit to see what we can do with it.

Functions for which we have a guess

-(BOOL)selectionShouldChangeInTableView:(CPTableView)aTable

     This function is called within _sendDelegateSelectionShouldChangeInTableView, and if the delegate function does not exist, the function defaults to YES.  This is apparently what allows us to change the selected row by clicking on other rows.  If this returns NO, it might possibly lock the selected row in place as the permanently selected row, or prevent the selection of any row at all.

-(CPView)tableView:(CPTableView)aTable viewForTableColumn:(CPTableColumn)aColumn row:(CPInteger)aRowIndex

    This function is called within _sendDelegateShouldEditTableColumn:(CPTableColumn)aColumn row:(CPInteger)aRowIndextableView:dataViewForTableColumn:row:   The table defaults to a return value of Nil if a delegate does not provide this function.  This function is passed to our dataSource as well, so it is curious that the table is possibly sending this function to the data source as well as the delegate.  Does this mean that we might be able to use a delegate as the data source if we wished?

-(CPView)tableView:(CPTableView)aTable dataViewForTableColumn:(CPTableColumn)aColumn row:(CPInteger)aRowIndex

    This function is called within _sendDelegateShouldEditTableColumn:(CPTableColumn)aColumn row:(CPInteger)aRowIndextableView:dataViewForTableColumn:row:   The table defaults to a return value of Nil if a delegate does not provide this function.  This function is passed to our dataSource as well, so it is curious that the table is possibly sending this function to the data source as well as the delegate.  Does this mean that we might be able to use a delegate as the data source if we wished?

-(void)tableView:(CPTableView)aTable  didClickTableColumn:(CPInteger)columnNumber

  This function is called from _sendDelegateDidClickTableColumn, which is called from table view's method _didClickTableColumn.  It returns no value, and merely says here is the table that was clicked, and this is the column number is clicked: do something with this information.

-(BOOL)tableView:(CPTableView)aTable shouldEditTableColumn:(CPTableColumn)a Column row:(int)aRowIndex

Do we have permission to edit this column?  I don't know, let's ask the delegate.  The delegate is provided the same information that is provided when requesting a cell data object, which means we can return a different result for each row, based on the data that is displayed.  The default value, if the delegate either does not exist or does not respond to the selector, is YES.

Other functions that request permission:

Some other functions that simply ask for permission to do an action and require no explanation:

-(BOOL)tableView:(CPTableView)aTable shouldSelectRow:(CPInteger)aRowIndex

-(BOOL)tableView:(CPTableView)aTable shouldSelectTableColumn:(CPTableColumn)aColumn

-(BOOL)tableView:(CPTableView)aTable shouldShowViewExpansionForTableColumn:(CPTableColumn)aColumn row:(CPInteger)aRowIndex

-(BOOL)tableView:(CPTableView)aTable shouldTrackView:(id)aView forTableColumn:(CPTableColumn)aColumn row:(CPInteger)aRowIndex
-(BOOL)tableView:(CPTableView)aTableView shouldReorderColumn:(CPInteger)columnIndex toColumn:(CPInteger)secondColumnIndex

While it is clear that these functions merely ask for permission to allow a section to occur or some other action, not all the actions are necessarily clear.  For example, what does it mean to permit tracking a view, or showing a view expansion?  The view expansion seems straight forward, but who provides the expanded view?

We have seen no functions thus far that might do this, except possibly the data view provider: maybe the table calls the data source for the primary data view and the data view extracted from the delegate is the expansion view?  We don't know yet.  Not enough has been tested to validate these concepts.

-(CPString)tableView:(CPTableView)aView toolTipForView:(id)aView rect:(CGRect)aRect tableColumn:(CPTableColumn)aColumn row:(CPInteger)aRow mouseLocation:(CGPoint)aPoint

This one seems rather obvious.  The table says, "Here is the a reference to me, a view that is involved, another region or rectangle, contained within this column on this row with the mouse located at this location, so give me a string that I should relay to the user."  Why do we need all those views rectangles and extra information?  What is the difference between them?  I don't know the answers to these questions, yet, which is why this function is still in the "Functions for which we have a guess column".

-(BOOL)tableView:(CPTableView) shouldTypeSelectForEvent:(CPEvent)anEvent withCurrentSearchString:(CPString)aString

See next function as well.

-(CPString)tableView:(CPTableView) typeSelectStringForTableColumn:(CPTableColumn)aColumn row:(CPInteger)aRowIndex

Here, we address two functions above, the shouldTypeSelect... and the typeSelectString... functions.  Originally the first function was in the "Functions for which we have no clue," but after finding the second function, we now have a reasonable guess.

Here is the scenario.  The table view says to your delegate: "We received an selection event (or some other event), do you want us to select a bunch of different data as a result?  If yes, what string should we use to determine which items are selected and which are not selected?"  This is a big guess, but I feel as though it is reasonable.  Look for delegate functions that involve selection and a search string to complete the selection triad, but this could be a fun delegate function to play with when one has the time.

-(CPMenu)tableView:(CPTableView)aTableView menuForTableColumn:(CPTableColumn)aColumn row:(CPInteger)aRowInteger

TableView says to your delegate "Here's the mouse hover information, should I display a pop-up menu?"

Functions for which we have no clue (at this time)

-(float)tableView:(CPTableView)aTable heightOfRow:(CPInteger)rowIndex

   From what I can tell, this function gives the delegate a chance to set a different row height for every row of the table based on the rowIndex (about to be printed, perhaps?) and the table view itself.

-(BOOL)tableView:(CPTableView)aTable isGroupRow:(CPInteger)rowIndex

  If the delegate does not handle this function, then the table acts as though the delegate responded NO.  From the title of the function, it seems to be a chance for the delegate to associate multiple rows as part of a larger group by simply indicating YES or NO.  It would naturally follow that perhaps some other function would be called next if YES is returned, but at this time we don't know what that would be.

-(int)tableView:(CPTableView)aTable nextTypeSelectMatchFromRow:(int)aRowIndex toRow:(int)aSecondRowIndex forString:(CPString)aString

I'll admit that I don't have a clue what this does.  I'm guessing it gives us the opportunity to search two rows for a common string and possibly return the number of matches or the matching column index.  It will require some investigation to be sure.

-(CPIndexSet)tableView:(CPTableView)aTable selectionIndexesForProposedSelection:(CPIndexSet)anIndexSet

I don't even know what an index set is, yet, but when I find out, I'll let you know.  As a result, I have no idea what this function might allow us to do.

Some of these methods listed here have seemingly clear purposes.  Some of them do not.  We will not play with all of them.