All DatabasesMacTech Vol 13-1997
StoneTable
Volume Number: 13
Issue Number: 12
Column Tag: Tools of the Trade
StoneTable
by Edward Ringel
This List Manager replacement offers many advantages to
the Mac OS developer
The visual management of list and tabular data is one of the weak points of the Mac OS
Toolbox. Although each programmer may have his or her pet peeve about the List
Manager, most developers would agree on three substantial limitations. First, and I
think foremost, is the 32K data limitation. Although it is possible to write an LDEF to
overcome this limitation without too much difficulty, we're still left with the fixed
cell size and absence of cell styles. Granted, for some applications, the List Manager
routines may be more than enough. On the other hand, for anyone with the need to
manipulate larger amounts of data, or with the need to customize rows, columns, and
cells, it can be pretty easy to bump up against the limitations of the List Manager.
After seeing StoneTable advertised repeatedly in MacTech and looking at their demos, I
thought it might be of interest to the Mac programming community to explore this
product in depth, as it is the only (at least to my knowledge) freestanding commercial
List Manager available to the Mac programming community. StoneTable is a powerful
List Manager replacement that offers many improvements over the List Manager
routines. Its current competition lies primarily in some of the components of
frameworks and one piece of almost freeware that we'll mention briefly at the end of
the article.
Package Contents
I received StoneTable via the Internet, which is currently the normal means of
distribution. The archive was about 1 meg. After decompressing the package, I
reviewed several different documents and files. There is the usual read me about bugs
and the like. This document, addressing version 3, indicated that there were no known
bugs. There was a longer document reviewing the changes between version 2 and
version 3. Although there was a host of information there about the differences
between versions, there was no hand-holding about how to do the conversion.
The primary description of the product is an Acrobat file which is a model for software
package documentation. It is clear, concise, and well written. The introduction and
general principles of operation are very helpful in setting the "ground rules" for the
package. The function nomenclature is uniform, as are function descriptions. The
document makes nice use of hypertext cross referencing. I would have liked to see
snippets of example code in the function descriptions, but I could also see that as
excessively burdensome for the author given that he provided a sample program as
well.
The software itself consists of a .h file, a .p file, libraries, procedural code examples,
TDEF development instructions (covered below) and a PowerPlant class and sample
app based on StoneTable. The package I received had CodeWarrior files for 68K
application and code resource (A4) development as well as a PPC lib. The sample
programs and projects work under the new CodeWarrior Pro IDE. The sample program
is fairly simple and does not show off every last feature of StoneTable. However,
careful review of the code definitely will show the programmer how to get started and
use the library effectively.
Lots More Than the List Manager
StoneTable performs many, many useful tasks. Obviously, it does everything that the
List Manager does. The additional functionality is why people pay money for this
product. StoneTable supports tables of data that are greater than 32K in aggregate size.
It allows many different cell data types. Text, checkbox, popup menu, PICTs, icons (all
sizes), hierarchical lists, and CDEF controls are all supported. A wide variety of style
information can be attached to each cell: justifications, font, size, margins, and
foreground and background colors are all options. If necessary, the programmer can
write a TDEF to support a custom drawing procedure. TDEF's are Table DEFinitions
supported by StoneTable. A prototype sample TDEF is provided as part of the package.
Text entry into tables is quite sophisticated. One of the very nice features of StoneTable
is in-cell editing, which for some programmers is the holy grail of lists. Cell data
entry validation hooks and stubs, as well as built-in validations for numbers, help
insure data accuracy. Sort and find functions are provided. Comprehensive control
over list appearance and behavior can be achieved with TDEF's and other hooks, stubs,
and callbacks provided by the library for the programmer. Many of the appearance
services are provided in such a manner so that the end user of the application can
easily control list appearance with a minimum of programming on the part of the
developer.
There are a host of other very useful services provided. Drag and drop and clipboard
management, while not terribly difficult to write, are a nuisance, tedious, and
error-prone routines. These two services require almost no programming to
implement. Drag and drop services in particular are quite sophisticated and include
transfers to and from StoneTable and non-StoneTable applications in either direction.
Clipboard information includes all cell data.
Using StoneTable
The programmer must first create a StoneTable list, and then intercept events directed
at the list and allow the StoneTable library to process the event. Table creation is not
awful, but requires multiple function calls to set display and interface options
completely. This is the kind of situation that could lend itself nicely to a resource that
is created by the programmer and then passed to a single MakeTable() call.
To intercept table events, StoneTable requires some modification of the basic event
loop, but overall this is not an onerous task. Because many unique services are
provided, the program must give the StoneTable library the opportunity to intercept
events that are directed at a StoneTable list. This is done by intercepting various
mouse clicks and keyboard events, as well as activate/deactivate events, etc. I have
lifted, with some modification, the conceptual outline of table creation and a typical
procedural event loop from the manual (my apologies to Bill Stackhouse for any
corruption or obfuscation.)
//The general outline of an application that uses StoneTable.
#include
...
create_table() {
...
window = NewWindow(...);
...
new_table = TMX_New(...);
//Create a new table and a ttach it to a window, then set the various
options
TMX_SetOptions(...);
TMX_SetGrid(...);
TMX_SetColumnTitleText(...);
TMX_SetRowTitleText(...);
//Now set the cell data
TMX_SetCellText(...);
//Now draw the list
TMX_DoDraw(...); /* set drawIt to TRUE */
...
}
//event loop
process_event(event) {
switch (event.what) {
case nullEvent:
//Take care of table idle events along with program idle events
TMX_Idle(...);
TMX_WhatCursor(...);
TMX_Where(...);
...
case mouseDown:
//Take care of table mouse down events along with program mouse down
events
TMX_Click(...);
...
case updateEvt:
//Process update events
TMX_Update(...);
...
case activateEvt:
//Process activate events
TMX_Activate(...);
...
case keyDown:
case autoKey:
//process table key events and simultaneously hands off non-table
events to the program
if ( ! TMX_KeyNav(...))
...;
}
}
StoneTable, like the List Manager, makes the programmer do a lot of work to fill the
list. StoneTable does provide one function that will take tab delimited text data and load
cells en masse, but other kinds of data must be loaded cell by cell. At first, I thought
this was a considerable failing of the product, but as I thought about it more, I realized
that it would be quite difficult to automate loading cell data. Similarly, saving a table to
a file would require a custom function written by the programmer. This discussion
can't help but raise the issue of transferring data back and forth between a program
memory structure in which the data is manipulated to a StoneTable structure in which
the data is displayed. With correct programming technique, I do not think it would be
necessary; StoneTable could keep it all without too much difficulty. These pros and
cons notwithstanding, it still might be advantageous to be able to store a StoneTable
"persistent object," and this might be a future goal of StoneTable upgrades.
In general, StoneTable calls are modeled after the List Manager calls, so the transition
is at least somewhat intuitive. Additionally, the StoneTable PowerPlant object is
modeled after the LTable class, also simplifying the transition as much as possible.
Memory Issues
Memory needs have the potential to be substantial. Each row and each column, requires
about 24 bytes allocated. Empty cells take no memory. Those that have data are stored
in a tree structure for quick access. Each allocated cell uses a minimum of about 46
bytes which includes style information for that cell. This uses more memory, but
apparently is faster than having the style allocated only if different from the default.
Memory is allocated using a memory manager that sits on top of the Mac Toolbox
Memory Manager. This internal memory manager allocates memory from large
handles. Titles other than default letters and numbers are treated as a regular cell.
Numbers and text are both stored as text as in the List Manager. If necessary, the
programmer can store binary data in the cell. Apparently, there have been no
complaints to StoneTable about performance due to numeric data.
The Finished Product
Judging from the available demo program and the sample program, it's not too difficult
to create a very handsome table that is very responsive to user actions. I ran the
sample program in 68K mode on my trusty Performa 6200 as well as PPC mode. The
68K mode was adequate, and the PPC program was downright snappy. Given the
number of lines of sample code, the control over the list's appearance and the quality
of the user interface is very impressive.
Figure 1. Window from StoneTable sample program.
The Competition and the Bottom Line
Although I have not made an exhaustive search of the products out there, I don't know of
any current, commercial, free standing List Manager Replacement except StoneTable.
There is an interesting product called the A list, which is almost free. It has many good
features, but does not have the speed or full feature set of StoneTable. From a
commercial standpoint, it is not bug free and is not supported in the same manner as
StoneTable. In particular, I found the code to be much slower than StoneTable, which
would be a serious issue with big lists.
PowerPlant and TCL both have table objects. The VIP-C and VIP Basic products support
a grid, which is quite powerful. In all of these frameworks, it would be hard to justify
a StoneTable purchase for simple tables. It would be cost efficient, however, to
purchase StoneTable for a complex list problem. Both Tools Plus and AppMaker are
"StoneTable aware" which makes it much easier to use this product in those
environments. I think it would be almost foolhardy to create a List Manager
replacement from scratch if you were programming in straight C, Pascal, or C++
without using a framework; StoneTable would be a logical choice.
All in all, StoneTable is a solid, useful tool for table management. Many programmers
will not use its full array of functions. StoneTable tables in an application will be well
behaved and easy to implement. Some framework programmers may be content to use
the "native" table object, but many framework developers may still benefit from using
StoneTable's unique features. In particular, in light of the recent price decrease and
version increment, StoneTable may warrant careful evaluation. We would be most
fortunate if all "niche" products were this good.
Products Reviewed
StoneTable, version 3.0 $199. Available from Developer Depot and directly from the
publisher, Stone Table Publishing, P.O. Box 12665, Portland, OR 97212. (503)
287-3424.
Useful URL's
StoneTablet publishing has a web site, ftp site, and email address. When you purchase
the product, you can join a list to be notified of updates, issues, etc.
http://www.teleport.com/~stack
ftp://ftp.teleport.com/pub/vendors/stack
stack@teleport.com
Demo available at:
ftp://ftp.teleport.com/pub/vendors/stack/StoneTableDemo.hqx
______________________________
Ed Ringel, eringel@mint.net, is Contributing Editor for product reviews for MacTech
Magazine. In his spare time, he is a respiratory and critical care physician in
Waterville, Maine.
Referenced by (10):