ListWindow Package

                                07/04/90
                         (c) 1990 by Paul Miller


The ListWindow Package (listwin_pak) is a useful package of simple functions
for quick and easy programming of list window operations.

The package gives simple initialization, handling, and freeing of Macintosh-
like "list-windows." These are user-sizeable windows with a scrollable list
of text strings, optionally sortable. The list can be scrolled with a scroll-
bar, up and down arrows, arrow keys, or a SHIFT+key combination which
searches for the first occurance of the specified key in the name list, and
sets the top of the list to that name (this is optional). All list-window
control functions use a pointer to the window as a handle, so your program
doesn't need to know anything about the internal manipulation of the lists.
However, you can't use your Window->UserData pointer as the list-window
package makes use of this.

This package is ideal for programs that display a list of commands, names,
type sizes, fonts, etc, that need to be scrolled through, or can, optionally,
be sized to the likes of the user. For example, If you are working on a ray-
tracing program that has an indefinite number of available textures for
mapping onto surfaces, you could make the list available within a list-window
so the user can see as much of the list as he/she wants.

When a name is selected, the string is copied into an application-supplied
buffer. The application program then uses this buffer to compare to its
internal list of name strings. Since the list of names is sorted by the list-
window package, returning the position of the name in the list may not have
anything to do with the position of the name within the application. An array
of pointers to text strings is used as the base of the list-window, kept
within a NameList structure. The ListWindow Package also has functions used
in allocating, copying, sorting, and freeing NameLists.

If a name is selected, and the list is scrolled, the "slot" that the name was
in will remain hilighted and whatever name scrolls "under" the slot will be
copied into the buffer and the application program will be notified of a name
selection. This is provided in case you want "real-time" information update
as the list is scrolled.

Note that I am NOT using Gadgets for name selections, but I am just reading
mouse positions and decoding the slot position from that. After a long bit
of frustration with dynamic allocation/deallocation of gadgets whenever the
window is re-sized, I discovered that a bug in Intuition caused HUGE fragmen-
tation when the window was sized smaller. All the memory was released, but
the maximum available memory chunk was reduced to about 22K or less, which
wasn't enough to even change the size of the window again. I think this
boiled down to the RefreshGList() function and internal clip-rects and stuff.
Anyway it's too much of a pain, so I use the simple old-fashioned (and
less memory-hungry!) way.


Don't forget to include the "listwin_pak.h" file in your programs.

Refer to "listwin_pak.doc" for more info.

See the included "Test" program for an example of setting up a ListWindow.

Feel free to use these functions or the object module in your programs. If
you end up just linking in the listwin_pak.o object module, kindly mention
me in your credits, eh? -Enjoy.