The A List

By Kyle Hammond
kyle [dot] hammond [at] snowmintcs [dot] com

Please note that The A List is very nice if you're programming for Mac OS 7.x - 9.x. If you're doing programming for Mac OS X, there are much more modern solutions that Apple provides for you to use.

I wasn't satisified with Apple's List Manager (part of the Mac Toolbox) and so decided to write my own. I based the API on Apple's List Manager and also on the WASTE API.

The first thing to note is that I use a few callback functions that enable the list to display ANY kind of data that you want it to; so there are no LDEF's to compile and work with. Since the data is stored in the list as a simple void *, the size of lists can be enormous. Also, it works great on PowerPC computers and is faster than Apple's List Manager on large lists.

The A List is directed at application developers who require (one dimensional) lists and want more flexibility and control than Apple's List Manager gives them.

The A List achieved Carbon compatibility with version 1.1.7. You can use The A List with System 7.0 through MacOS X. The A List uses the Carbon functions TrackMouseLocation and TrackMouseRegion for giving up processing time within ALClick, the mouse down function, so other processes run smoothly.

Defining the Problem

If you've used Apple's old List Manager, you've probably run into the fact that it doesn't support large lists, cut, copy, paste, drag-and-drop, or just about anything else that's been invented in the last ten years.

Also, since Apple's old List Manager uses LDEFs to do the drawing, it is not as simple as it could be to change some part of the list drawing code as your application changes.

The Simple (For You) Fix

The simple fix to the problem is to replace all calls to the List Manager with (almost) identical calls to The A List. The main call that is different is ALNew (instead of LNew). ALNew takes a few more parameters than LNew.

With simple text lists, when inserting the data, make sure that the ALData is actually a StringHandle. The default list callbacks take care of cut/copy/paste/drag operations, drawing and even disposing of the StringHandles as necessary (when rows are removed, the entire list is deleted, etc.).

Extending the Simple Fix

If you need/want to use data other than simple StringHandles, you will need to provide at least one and probably more callback functions.

The most likely custom callback is used to draw the cell. The callback prototype is this:
ALIST_API void MyDrawCellProc(ALData cellData, ALCellPtr cell, LongRect *cellRect, ALReference hAL);

Another callback you may want to use takes care of hiliting the cell. The default callback simply inverts or outlines the cell with the user-selected hilite color. The callback prototype is:
ALIST_API void MyHiliteCellProc(ALData cellData, ALCellPtr cell, Boolean active, Boolean doOutline, LongRect *cellRect, ALReference hAL);

The third callback is to dispose of the data. The callback prototype is this:
ALIST_API void MyDisposeCellDataProc(ALData cellData, const ALCellPtr cell, ALReference hAL);

All of the callbacks, as well as most of the API, are documented in the on-line documentation.

Wish List & More Comments

I never use Apple's old List Manager any more. One of the first things I used to do when receiving a new Codewarrior update is to comment Lists.h out of the MacHeaders.c file (and uncomment QDOffscreen.h).

The following are some of the things I'd like to see implemented for The A List:

Note: These things will probably never get done because I don't program for Mac OS 7.x - 9.x anymore.

License Agreement

The A List is essentially free, but you have to give me credit. Of course, any donations are always accepted. Read the ReadMe file included in the download for further information.


Other References


Thanks to Sebastiano Pilla for developing the A List Pascal Adaptation Kit.

Thanks to Marco Piovanelli for developing the great WASTE library.

Thanks to all the people who've submitted bug reports and suggestions. Without a bit of encouragement this wouldn't be nearly as good.

Programs Using The A List

Old versions of DrScheme by Rice University - DrScheme is a graphical environment for developing programs using the Scheme, MzScheme, and MrEd programming languages.

GetMultiple.c by Kyle Hammond - an easy to use code snippet that asks the user for multiple files using CustomGetFile and The A List.

Object Plant by Mikael Arctaedius - a shareware program for Object-Oriented Analysis and Design. The notation used by the Object Plant is based on the Object Modeling Technique (OMT) but also supports a subset of the Unified Modeling Language (UML).

Old versions of SeqMan II by DNASTAR, Inc. The DNA-Fragment Assembler (it sequenced E.coli K12).

Spell Catcher 8 by Rainmaker - This sleek user interface makes it easy to look up definitions, pronunciations, thesaurus entries, to check spelling, and more.

UGather by Kyle Hammond - a multimedia database manager.

UPresent by Kyle Hammond - a multimedia presentation manager. Handles many media types (images, QuickTime movies, 3DMF files, live video, other applications, videodisc players, text cards, URLs) in an easy to use environment.

Go to my home page.

Send feedback to