Tableviews
**********

A tableview is a grid of rows and columns for the display of data. In the AppKit, you use the NSTableView class to put a tableview in your application.

Gorm already has a palette set up for a tableview, that you can simply drag and drop onto your application window (refer to the sections on Gorm and the Gorm manual).

More involved, however, is getting data into your tableview and responding to certain tableview specific events. Both of these are implemented using objects that respond to certain protocols, as described below.

Columns
=======

Instead of taking an array oriented model of a table, the NSTableView class uses a column-oriented model, where columns are used as objects of separate classes, NSTableColumn.

These can be instantiated with the -initWithIdentifier: method, where the identifier is an internal object, not displayed, used by the data source (see below) to identify what column data should be placed in. You can retrieve the table column's identifier from the -identifier method.

This column-oriented model for displaying data makes tableviews useful for information originating from a database, where columns are akin to fields, and each row represents a record in a table or query.

FIXME: How do you initialize a table's column's and it's identifiers when a nib is loaded. Do you use one of it's delegates methods to set all this stuff up?

Supplying Data
==============

When you first create your tableview, Gorm puts some example data into it for you. However, you will want to put in your own data. GNUstep uses a data source model, which means that you need to supply an object that will provide data for your table view.

Firstly, you will need to connect the dataSource outlet of a tableview in Gorm to an instantiated object of a class. Create a class that will have it's objects provide data for your tableview(s), and instantiate it so that it appears as a top level object in the Objects pane.

Your object will need to implement an informal protocol to supply data to the tableview, namely the NSTableDataSource protocol (for more information on informal protocols, see the GNUstep Base Programming Manual).

Most of the methods in this protocol are optional. The compulsory methods, however, are called quite often, so you should optimise them so that they run as fast as possible.

The -numberOfRowsInTableView: method is called to determine how many rows are to be shown in your table view. This could change from time to time, and as the data in your table view changes, you will need to inform the NSTableView object that data has changed (usually via the -update method). When it performs it's update, it will use this method to determine how many rows to draw. This method is compulsory to implement, and your will experience errors if you don't implement it.

Another compulsory method is the -tableView:objectValueForTableColumn:row:. This is used to get the data that the table view will put in it's cells. It will pass you the table column that the cell appears in, the cell's row, and the associated tableview. The method returns an object to be displayed in the relevant cell; this object is usually a string.

Note that if the data to be displayed in a tableview changes, it has no way of knowing if and when it has changed. For this reason, you need to call -update manually on the tableview to force it to redisplay. Only then will it again invoke the methods above on your data source.

If you want your tableview to be editable, you will need to implement the -tableView:setObjectValue: forTableColumn:row: method. You use this to update your internal representation of what is displayed in the table view to the user.

Both these methods supply a reference to a tableview as well, so the same object (or objects of the same class) can be used as a data source for more than one tableview (e.g. across many documents, or for many tables in a database).

You can setup your tableview to accept drop operations. It must implement -tableView:writeRows:toPasteboard:. This method is called first, and is asking you to write the data in the specified rows to the specified pasteboard. This method should return YES to authorise the drop, or NO to reject it. More methods that can be implemented to provide information to the tableview during a drop operation include -tableView:acceptDrop:row:dropOperation: and -tableView:validateDrop: proposedRow:proposedDropOperation: methods. These are used to validate and accept drop operations, where the latter is called to validate a potential drop operation, the former just before a validated drop operation is about to take place.

If the data in your data source changes for any reason, e.g. the action of a user, you must notify the tableview. You could do this by calling -reloadData on the tableview object, which you can reference by an outlet on your application's controller class (or otherwise).

Delegates
=========

Tableviews support a delegate for catching certain events in the lifetime of an NSTableView object. You will need to implement the informal NSTableViewDelegate protocol. This is different from the data source - you implement a delegate if you wish to catch tableview specific events created by the user.

Notifications
=============

A tableview many post notifications to indicate changes to it (that otherwise are not sent to the delegate) such as user selection changes or the reordering of columns or rows.