January 94 - Using TGridView
Using TGridView
Bob Hablutzel
This is the second article in what will hopefully be a monthly series of technical
question and answers on object oriented programming. The intent of this column is to
go beyond simple answers. I intend to take a question, answer it, and then use that
question as a springboard to a more general discussion on programming. I hope you
find the results interesting.
The first articles will be culled from frequently asked questions on MacApp3Tech$,
but I need your questions! I can be reached electronically at AppleLink: B.HABLUTZEL;
by telephone at 708.328.0130; by fax at 708.328.2417 or by post at Bob Hablutzel,
Hablutzel Consulting, 606 Asbury, Evanston, IL, USA 60202.
QI would like to display a list of strings. MacApp seems to have a class for doing just
this (TTextListView), but I cannot figure out how to attach the TList to it. How is the
list associated with the view?
AThe immediate answer is that the list in TList and the list in TTextListView are not
the same list. Unfortunately, it appears from the names of the classes that they were
designed to go together. While they do work nicely together, it is not as transparent as
the names would imply.
To understand the problem, we need to take a step back and look at the overall view
hierarchy. In general, the view classes are fully functional; you can instantiate them,
and they will perform the actions you expect. The classes in the category include
TView, TButton, TRadio, etc.
A few of the view classes, however, are really abstract superclasses, and are not
meant to be instantiated. TGridView, TTextGridView, and TTextListView all fall into
this category. They are there for you to customize, not for you to use as–is. Another
important fact to realize is that the classes, unlike the toolbox List Manager, do not
maintain the data for you; this is something you need to maintain in the subclass you
create.
TGridView, the parent of these views, describes a basic cell-oriented view. It knows a
great deal about displaying cell oriented data: how to select cells, how to scroll cells,
managing different column widths and row heights. It explicitly does not, however,
know how to draw any particular cell.
This makes some sense, from a framework perspective. There is really no way to
predict what kind of cell you will be imaging, and therefore it makes sense to make no
assumptions. This leaves the doors open to icon cells, text cells, numeric cells, or even
a mixed bag of all of these.
What TGridView does define, however, is a routine that is called to draw a particular
cell. This routine, TGridView::DrawCell(), takes two arguments. The first argument
defines which cell is being imaged. The cell is passed as a point–like structure defining
the column and row numbers of the cell. The second argument is the rectangle to draw
into.
If you decide to implement a view based on TGridView, you need to override DrawCell.
(You may not need to override any other method). In the DrawCell override, you would
determine the data you are going to image (based on the column and row numbers
passed in), and draw the data. Again, this data can be anything you choose; you are in
complete control of the drawing.
The designers of MacApp realized, however, that text-only grids are very common and
important grid types. In order to make it easier to support these grid types, they
created the TTextGridView and TTextListView classes. In these classes, a text-only
override of DrawCell has already been provided for you, and you therefore do not have
to worry about the imaging of the data. You do, however, need to provide a means of
obtaining the data.
TTextGridView defines a view that understands multiple–column grids of text. It
defines a routine, GetText(), that takes two arguments. The first argument is the cell
to return text for, and the second is the text being returned. By default, this routine
returns an empty string, so if you include an unspecialized TTextGridView in your
programs, you will have the right number of cells, but nothing in them. You need to
provide an override to GetText to provide the text for the individual cells.
TTextListView defines a view that is subclassed from TTextGridView, and is specialized
to handle single–column grids of text. It overrides the default definition of GetText, and
in turns calls a more specialized TTextListView defined routine, GetItemText. This
routine takes two arguments, much like TTextGridView::GetText, but the first
argument is simply the row number, not the cell. This allows you to return the string
based on row number only.1
If you subclass either of TTextGridView or TTextListView, you need to at least override
GetText or GetItemText, respectively. This give the view some text to draw. Of course,
you need to get the text from somewhere. You basically have three choices: calculate
the data on the fly; store the data in the view; or store the data extermally to the view,
most likely in a document. The override of GetText/GetItemText needs to know how to
obtain the text given the cell/row number.
We have talked about displaying the data contained in a grid view, but there is another
problem to be solved: defining the number of rows and columns. For some applications,
this value can be pre-determined, and coded into your view creation (or set with your
favorite view editor). However, for most applications the size of the grid needs to be
determined at run time. TGridView provides a number of useful routines for handling
this problem, such as InsRowFirst to insert rows, InsColFirst to insert columns,
DelRowFirst to delete rows, and DelColFirst to delete columns.
Take, for example, the method TGridView::InsRowFirst. This routine creates a new row
of cells for data to be displayed in at the beginning of the grid. Since grid views do not
know about data, it has no way of affecting the data that corresponds to these cells. It is
your responsibility to manipulate the data to correspond to the new cell state. (More
properly, it is your responsibility to call this routines to manipulate the grid to
correspond to changes in the data's state.) The changing of the data, and the changing of
the display of the data, are two separate actions that need to take place simultaneously.
(This is also true for the routines that TTextListView defines, such as InsItemFirst.)
It is important to stress that these routines manipulate cells, not data. By adding or
deleting cells, you provide room for data to be displayed; you do not affect data in any
way. It is worth noting at this point that, if your grid view changes size and lives in a
scroller, you probably want to change the size determiner of the view to sizeVariable.
If you don't, the view will not really change size when you add or delete rows,
confusing the scroller.
There are a number of tricks you can use to make your life easier when managing the
number of cells. For example, you could make the grid view object dependent upon the
document it is associated with. Then, when the document data changes, the grid view
can catch the change in an override of DoUpdate, and adjust the number of cells
accordingly. Grid views provide a simple means of display cell-oriented data. You need
to remember that it is your responsibility to define a means for them to obtain the
data, and, in the case of direct TGridView subclasses, to display the data. You also need
to tell the grid how large it is, so that it can display the right number of cells for your
data. Forgetting either of these two actions will result in no data being displayed in the
view.
1 This might seem like a trivial reason for an override, and by itself it would be.
However, TTextListView also provides some functionality, such as type-selection, that
make sense for single column grids but not for multiple–column grids.