Palette Selection in Aztec C

By Mike Schuster, Adobe Systems, MacTutor Contributing Editor

Making Palettes with the List Manager

Apple's December 1985 Macintosh software supplement (which was shipped to “the rest of us” in March 1986) contains a variety of useful items, including the new List Manager Package. The List Manager provides a set of routines and data types for creating, maintaining and displaying lists and arrays of data elements. In its simplest form, you can use the List Manager to display a scrollable list of names, as in the Standard File Open dialog box. In other, more complex forms, you can use the List Manager to display arrays of arbitrary graphic images, as the displays of pictures and icons in the Resource Editor and the Chooser desk accessory.

Apple implemented the List Manager as a package (like the Standard File, Disk Initialization and International Utilities packages) and placed it (as package 0) in the System resource file (version 3.1.1) which is included with the supplement. The supplement also contains an alpha draft of the new List Manager Package chapter of Inside Macintosh Volume IV.

To show you what you can do with the List Manager, I used it implement a MacPaint-like palette of tools:

In this example, the palette is represented as a 2 column by 10 row array (only 5 rows of which are visible at any one time), where each list element is a MacPaint tool icon. I instructed the List Manager to display the array and its scroll bar in a rectangle within its own window. Once the array is setup, the List Manager handles all mouse events, selections, and scrolling of the icons within the palette.

The List Manager provides a variety of display alternatives. In the following two example, I arranged the palette as 10 column by 2 row array and as a 20 column by 1 row array.

In the following example, the palette is arranged as a 10 column by 2 row array, where the whole palette is visible in its window, and so a scroll bar is not needed.

The List Manager's Structure

The List Manager is designed to maintain a set of data elements within a list, and to display the list in a rectangle within a window. The data elements themselves are displayed in the rectangle as a two dimensional array of cells. Although the size of each data element may vary, the cells in which they are displayed must be the same size. When you create the list, you specify the horizontal and vertical size of a cell, as well as the number of rows and columns of cells the list is to contain. After the list is created, you can at any time add new rows or columns to the list as well as delete existing rows and columns. The cells in a new list and in any new rows and columns are initially empty.

Once you have created the list, or added rows or columns, you can set the values of the cells. The value of a cell is any arbitrary consecutive sequence of bytes of data, with the restriction that the total size of a list cannot exceed 32K bytes. Hence, a cell can store most anything - a text string, the bits of an icon, or the resource ID of a picture.

At any given time, only a subset of the cells in the list may be visible in the list's rectangle within the window. The set of visible cells is determined by the size of a cell, the number of rows and columns in the list, and the current horizontal and vertical scrolling positions.

The location of each cell in a list is specified by its row and column number. The top-left cell in the list is in column 0 and row 0. The bottom-right cell in the list is in column c-1, row r-1, where the list contains c columns and r rows. The List Manager uses the Quickdraw Point data type to specify a cell's location. The horizontal coordinate specifies the cell's column, and the vertical coordinate specifies the cell's row.

The List Manager calls a list definition procedure, which is normally stored as a resource in a resource file, to draw and hilite the data elements within a cell. Apple supplied a default text-only procedure with the software supplement. For the palette, we'll have to write our own custom procedure to draw and hilite the palette's icons.

The List Manager routine LNew creates a list, and returns a handle to the new list.

ListHandle LNew(rView, dataBounds, cSize, theProc, theWindow, drawIt, 
hasGrow, scrollHoriz, scrollVert)

Rect *rView, *dataBounds;
Point cSize;
int theProc;
WindowPtr theWindow;
Boolean drawIt, hasGrow, scrollHoriz, scrollVert;

The list will be displayed in the window specified by theWindow. RView specifies, in the local coordinates of theWindow, the rectangle in which the list will be drawn.

The rectangle DataBounds specifies the initial dimensions of the list. Its top and left coordinates should both be 0. Its bottom coordinate specifies the number of rows in the list. Its right coordinate specifies the number of columns in the list. The point cSize specifies the size of each cell. Its horizontal coordinate specifies the width of a cell. Its vertical coordinate specifies the height of a cell.

TheProc is the resource ID of the list definition procedure that will be used to draw and hilite the data elements within the cells. For the default text-only list, pass 0 and Apple's default list definition procedure will be used.

If scrollHoriz is TRUE, the List Manager will place a horizontal scroll bar immediate below rView in the window and will enable all of the list's horizontal scrolling functions. Similarly, if scrollVert is TRUE, the List Manager will place a vertical scroll bar immediately to the right of rView in the window and will enable all of the list's vertical scrolling functions. If hasGrow is TRUE, the scroll bars are sized to make room for a size box in the standard position.

DrawIt specifies the initial value of the list's drawing mode. If the list's drawing mode is TRUE, all routines that affect the contents of cells, the number of rows and columns in the list, the size of the window, or which cells are visible within the rectangle, will cause the updated list to be drawn. If the list's drawing mode is FALSE, none of these operations will cause the updated list to be drawn, until the drawing mode is later set to TRUE, using the List Manager routine LDoDraw.

void LDoDraw(drawIt, lHandle)
 Boolean drawIt;
 ListHandle lHandle;

LDoDraw sets the list's drawing mode to the state specified by drawIt.

The ListHandle returned by LNew is defined as follows. For a more detailed description, refer to the List Manager Package chapter in the supplement.

typedef Point Cell;

typedef struct
 {
 Rect rView;/* list's display rectangle */
 GrafPtr port;   /* list's grafPort */
 Point indent;   /* indent distance */
 Point cellSize; /* cell size */
 Rect visible;   /* boundary of visible cells */
 ControlHandle vScroll; /* vertical scroll bar */
 ControlHandle hScroll; /* horizontal scroll bar */
 char selFlags;  /* selection flags */
 Boolean lActive;/* TRUE if active */
 char lReserved; /* reserved */
 char listFlags; /* automatic scrolling flags */
 long clikTime;  /* time of last click */
 Point clikLoc;  /* position of last click */
 Point mouseLoc; /* current mouse location */
 Ptr lClikLoop;  /* routine for LClick */
 Cell lastClick; /* last cell clicked */
 long refCon;    /* list's reference value */
 Handle listDefProc; /* list definition procedure */
 Handle userHandle;/* additional storage */
 Rect dataBounds;/* boundary of cells allocated */
 Handle cells;   /* cell data */
 int maxIndex;   /* used internally */
 int cellArray[1]; /* offsets to data */
 } ListRec, *ListPtr, **ListHandle;

The List Manager provides a variety of cell selection algorithms, and defines the following predefined flags for the selFlags field of the list record shown on the top of the next page.

#define lOnlyOne 128 /* set if only one selected cell */
#define lExtendDrag 64    /* set for dragging without shift */
#define lNoDisjoint 32    /* set  turns off multiple selects */
#define lNoExtend 16 /* set to not extend shift selects */
#define lNoRect 8/* set to not expand selections */
#define lUseSense 4/* set for shift to use first cell's        
 sense */
#define lNoNilHilite 2    /* set to not hilite empty cells */

For our purposes, only the lOnlyOne flag is useful, since only one icon may be selected from the palette at any time. Check the supplement for a description of the other flags.

Once the list is created, the List Manager routine LSetCell may be called to set the value of a particular cell in the list.

void LSetCell(dataPtr, dataLen, theCell, lHandle)
 Ptr dataPtr;
 int dataLen;
 Cell theCell;
 ListHandle lHandle;

LSetCell places the data pointed to by dataPtr and of length dataLen into the cell specified by theCell in the list specified by lHandle.

In addition to setting the value of a cell, the List Manager provides routines for selecting a cell as well as returning information about which cell (cells) is (are) currently selected.

void LSetSelect(setIt, theCell, lHandle)
 Boolean setIt;
 Cell theCell;
 ListHandle lHandle;

If setIt is TRUE, LSetSelect selects the cell specified by theCell in the list specified by lHandle. If setIt is FALSE, LSetSelect deselects the cell.

Boolean LGetSelect(next, theCell, lHandle)
 Boolean next;
 Cell *theCell;
 ListHandle lHandle;

If next is FALSE, LGetSelect returns TRUE if the specified cell is selected, or FALSE if not. If next is TRUE, LGetSelect returns in theCell the cell coordinates of the next selected cell after theCell in row major order, and returns TRUE. If there are no selected cells after theCell, FALSE is returned.

The List Manager provides several routines that should be called in response to certain events.

void LActivate(act, lHandle)
 Boolean act;
 ListHandle lHandle;

You should call LActivate to activate or deactivate the list specified by lHandle in response to an activate event in the window containing the list. Act should be set to TRUE to activate the list, and FALSE to deactivate it.

void LUpdate(theRgn, lHandle)
 RgnHandle theRgn;
 ListHandle lHandle;

You should call LUpdate in response to an update event. TheRgn should be set to the visRgn of the list's window. LUpdate redraws the visible cells and the scroll bars, if necessary.

Boolean LClick(pt, modifiers, lHandle)
 Point pt;
 int modifiers;
 ListHandle lHandle;

Call LClick in response to a mouse-down event in the list's rectangle or its scroll bars. Pt is the mouse location in local coordinates. Modifiers is the modifiers word from the event record. The result is TRUE if a double-click occurred.

LClick keeps control until the mouse is released. If the pointer is in the list's rectangle, cells are selected appropriately. If the pointer was in the rectangle, but is dragged outside, the list is auto-scrolled. If the pointer was in a scroll bar, its control definition procedure is called to track the mouse, and the list is scrolled appropriately.

In addition to the 8 routines described above, the List Manager provides an additional 18 routines. Check the supplement for their description.

Implementing the Palette

With help of the List Manager, implementing the palette is relatively straightforward. First LNew is called to create a 2 column by 10 row list. Then LSetCell is called to set the value of each cell to the 128 bytes of the appropriate icon. The icons themselves are stores as ICON resources in the application's resource file.

Once the palette is created, the routines LActivate, LUpdate, and LClick are called in response to the appropriate events.

The routine IconListDef is our custom list definition procedure that draws and hilites the icons in their respective cells. A list definition procedure must have the following parameters:

void ListDefProc(lMessage, lSelect, lRect, lCell, lDataOffset, 
 lDataLen, lHandle)
 int lMessage;
 Boolean lSelect;
 Rect *lRect;
 Cell lCell;
 int lDataOffset, lDataLen;
 ListHandle lHandle;

The lMessage parameter identifies the operation to be performed. It has one of the following values:

#define lInitMsg 0 /* do any additional list initialization */
#define lDrawMsg 1 /* draw and optionally hilite the cell */
#define lHiliteMsg 2 /* invert the cell's hilite state */
#define lCloseMsg 3/* take any additional disposal action */

LSelect is TRUE if the cell should be selected. LRect is the rectangle in which the cell should be drawn or hilited. lCell identifies the cell's column and row. LDataLen is the length in bytes of the cell's data. LDataOffset is the offset into the list's cell data of the cell to be drawn or hilited. lHandle is a handle to the list record.

Our routine IconListDef ignores the lInitMsg and lCloseMsg, since no private storage is needed.

In response to an lDrawMsg, IconListDef uses the Quickdraw CopyBits routine to copy the bits of the icon from the list's cell data into the argument rectangle lRect. Then, if lSelect is TRUE, InvertRect is called to hilite the icon.

In response to an lHiliteMsg, IconListDef simply calls InvertRect to invert the hilite state of the icon.

Since LNew expects that the list definition procedure is stored as an LDEF resource in a resource file, I defined a 6 byte LDEF resource that contains the single instruction

 JMP    $00000000

Then, before calling LNew, the following code is used to modify the destination of the JMP instruction to the routine IconListDef:

 theLDEF = GetResource('LDEF', LDEF);
 *(long *) (*theLDEF + 2) = (long) &IconListDef;

This scheme is reasonable since the LDEF resource is non-purgeable and the IconListDef routine is in a non-relocatable CODE resource.

The application itself was written for the Manx Aztex C compiler.

/*
 * Palette List Application
 */

#include <event.h>
#include <inits.h>
#include <list.h>
#include <memory.h>
#include <menu.h>
#include <packages.h>
#include <quickdraw.h>
#include <resource.h>
#include <segment.h>
#include <toolutil.h>
#include <window.h>

#define MENUBAR 256
#define WINDOW 256
#define ICON 256
#define LDEF 256
#define GRABBER 256

#define WIDTH 26
#define HEIGHT 22
#define ROWS 10
#define COLUMNS 2

#define POINT(thePt) *(long *)(&thePt)

WindowPtr palette;

main()
 {
 MacInit();
 MenuInit();
 PaleInit();
 for (;;)
 EventDoOne();
 }

MacInit()
 {
 InitGraf(&thePort);
 InitFonts();
 InitWindows();
 InitMenus();
 TEInit();
 InitDialogs(0l);
 FlushEvents(everyEvent, 0);
 InitCursor();
 }

MenuInit()
 {
 SetMenuBar(GetNewMBar(MENUBAR));
 DrawMenuBar();
 }


pascal void IconListDef(lMessage, lSelect, lRect, lCell,       
 lDataOffset, lDataLen, lHandle)
 int lMessage;
 int lSelect;
 Rect *lRect;
 long lCell;
 int lDataOffset;
 int lDataLen;
 ListHandle lHandle;
 {
 char tag;
 BitMap iconBits;
 
BlockMove(lRect, &iconBits.bounds, (long) sizeof(Rect));
switch (lMessage)
 {
 case lInitMsg:
 break;
 
 case lDrawMsg:
 if (lDataLen)
 {
 tag = *(char *) (*lHandle)->cells;
 HLock((*lHandle)->cells);
 iconBits.baseAddr = *(*lHandle)->cells +                      lDataOffset;
 iconBits.rowBytes = 4;
 CopyBits(&iconBits, &thePort->portBits,                       lRect, 
lRect, srcCopy, 0l);
 *(char *) (*lHandle)->cells = tag;
 }
 else
 EraseRect(lRect);
 if (!*(char *) &lSelect)
 break;
 
 case lHiliteMsg:
 iconBits.bounds.right--; iconBits.bounds.bottom--;
 InvertRect(&iconBits.bounds);
 break;
 
 case lCloseMsg:
 break;
 }
}

PaleInit()
 {
 Handle theLDEF;
 Rect theView;
 Rect theBounds;
 int scroll;
 Point theSize;
 ListHandle theList;
 Cell theCell;
 int id;
 Handle theIcon;
 
 palette = GetNewWindow(WINDOW, 0l, -1l);

 theLDEF = GetResource('LDEF', LDEF);
 *(long *) (*theLDEF + 2) = (long) &IconListDef;
 
 SetRect(&theBounds, 0, 0, COLUMNS, ROWS);
 BlockMove(&palette->portRect, &theView, (long)                sizeof(Rect));
 if (scroll = (theView.bottom - theView.top) / HEIGHT <        
 ROWS)
 theView.right -= 15;
 SetPt(&theSize, WIDTH, HEIGHT);
 theList = LNew(&theView, &theBounds, POINT(theSize),          
 LDEF, palette, FALSE, FALSE, FALSE, scroll ?                  TRUE : 
FALSE);
 SetWRefCon(palette, theList);
 (*theList)->selFlags = lOnlyOne;

 for (id = 0; id < COLUMNS * ROWS; id++)
 {
 SetPt(&theCell, id % COLUMNS, id / COLUMNS);
 HLock(theIcon = GetIcon(id + ICON));
 LSetCell(*theIcon, 128, POINT(theCell), theList);
 HUnlock(theIcon);
 }

 SetPt(&theCell, 0, 0);
 LSetSelect(TRUE, POINT(theCell), theList);
 
 LDoDraw(TRUE, theList);
 ShowWindow(palette);
 }

EventDoOne()
 {
 EventRecord theEvent;
 WindowPtr theWindow;
 
 if (GetNextEvent(everyEvent, &theEvent))
 {
 switch (theEvent.what)
 {
 case mouseDown:
 switch (FindWindow(POINT(theEvent.where),                     &theWindow))
 {
 case inMenuBar:
 if (MenuSelect(POINT(theEvent.where)))
 ExitToShell();
 break;
 
 
 case inContent:
 if (theEvent.modifiers & optionKey)
 {
 SetCursor(*GetCursor(GRABBER));
 LActivate(FALSE, GetWRefCon(palette));
 DragWindow(palette, POINT(theEvent.where),                    &screenBits.bounds);
 LActivate(TRUE, GetWRefCon(palette));
 InitCursor();
 }
 else
 {
 SetPort(palette);
 GlobalToLocal(&theEvent.where);
 LClick(POINT(theEvent.where),     theEvent.modifiers, GetWRefCon(palette));
 }
 break;
 }
 break;
 
 case updateEvt:
 BeginUpdate(palette);
 LUpdate(palette->visRgn, GetWRefCon(palette));
 EndUpdate(palette);
 break;
 
 case activateEvt:
 LActivate(theEvent.modifiers & activeFlag ? TRUE :            FALSE, 
GetWRefCon(palette));
 break;
 }
 }
}

A Few Resources

The following file is a list of the resources used by the Palette application. The file Palette.app contains the linked application. The file Palette.icon contains the tool icons and application cursors. The file List.pack contains the List Manager package. (You don't need to include this file if the List Manager package resides in your System file, ie System File 3.1.1, the latest release.)

*

* Palette List Resources

*

Palette:Palette

APPLPALE

Include Palette:Palette.app

Include Palette:Palette.icon

Include Palette:List.pack

Type MBAR = GNRL

,256 (4)

.I

1

.I

256

Type MENU

,256 (4)

File

Quit

Type WIND

,256 (4)

Untitled

* bounds for 5 rows with scroll bar: 29 15 139 82

* bounds for 10 rows without scroll bar: 29 15 249 67

29 15 139 82

Invisible NoGoAway

2

0

Type LDEF = GNRL

,256 (4)

.H

4EF9 0000 0000

A List Manager Interface

The following file is the List Manager interface for Manx Aztec C. Each of the routine nubs first pops a return address off the stack, pushes the appropriate package routine selector word, pushes the return address back onto the stack, and then invokes the _Pack0 trap. The auto-pop bit in the _Pack0 trap word is set so that control returns to the invoking routine.

;
; Manx Axtec C interface to the List Manager
;
lActivate equ    0
lAddColumnequ    lActivate+4
lAddRow equ    lAddColumn+4
lAddToCellequ    lAddRow+4
lAutoScroll equ    lAddToCell+4
lCellSize equ    lAutoScroll+4
lClick  equ    lCellSize+4
lClrCellequ    lClick+4
lDelColumnequ    lClrCell+4
lDelRow equ    lDelColumn+4
lDisposeequ    lDelRow+4
lDoDraw equ    lDispose+4
lDraw equ    lDoDraw+4
lFind equ    lDraw+4
lGetCellequ    lFind+4
lGetSelectequ    lGetCell+4
lLastClickequ    lGetSelect+4
lNew  equ    lLastClick+4
lNextCell equ    lNew+4
lRect equ    lNextCell+4
lScroll equ    lRect+4
lSearch equ    lScroll+4
lSetCellequ    lSearch+4
lSetSelectequ    lSetCell+4
lSize equ    lSetSelect+4
lUpdate equ    lSize+4

public  .begin

_ListCall:
 move.l (A7)+,A0 ; pop return address
 move.w D0,-(A7) ; push routine selector
 move.l A0,-(A7) ; push return address
 dc.w $ade7 ; pack0, with auto-pop

 public LNew_
LNew_:
 moveq  #lNew,D0
 bra  _ListCall

 public LDispose_
LDispose_:
 moveq  #lDispose,D0
 bra  _ListCall

 public LAddColu_
LAddColu_:
 moveq  #lAddColumn,D0
 bra  _ListCall

 public LAddRow_
LAddRow_:
 moveq  #lAddRow,D0
 bra  _ListCall

 public LDelColu_
LDelColu_:
 moveq  #lDelColumn,D0
 bra  _ListCall

 public LDelRow_
LDelRow_:
 moveq  #lDelRow,D0
 bra  _ListCall

 public LAddToCe_
LAddToCe_:
 moveq  #lAddToCell,D0
 bra  _ListCall

 public LClrCell_
LClrCell_:
 moveq  #lClrCell,D0
 bra  _ListCall

 public LGetCell_
LGetCell_:
 moveq  #lGetCell,D0
 bra  _ListCall

 public LSetCell_
LSetCell_:
 moveq  #lSetCell,D0
 bra  _ListCall

 public LCellSiz_
LCellSiz_:
 moveq  #lCellSize,D0
 bra  _ListCall

 public LGetSele_
LGetSele_:
 moveq  #lGetSelect,D0
 bra  _ListCall

 public LSetSele_
LSetSele_:
 moveq  #lSetSelect,D0
 bra  _ListCall

 public LClick_
LClick_:
 moveq  #lClick,D0
 bra  _ListCall

 public LLastCli_
LLastCli_:
 moveq  #lLastClick,D0
 bra  _ListCall

 public LFind_
LFind_:
 moveq  #lFind,D0
 bra  _ListCall

 public LNextCel_
LNextCel_:
 moveq  #lNextCell,D0
 bra  _ListCall

 public LRect_
LRect_:
 moveq  #lRect,D0
 bra  _ListCall

 public LSearch_
LSearch_:
 moveq  #lSearch,D0
 bra  _ListCall

 public LSize_
LSize_:
 moveq  #lSize,D0
 bra  _ListCall

 public LDraw_
LDraw_:
 moveq  #lDraw,D0
 bra  _ListCall

 public LDoDraw_
LDoDraw_:
 moveq  #lDoDraw,D0
 bra  _ListCall

 public LScroll_
LScroll_:
 moveq  #lScroll,D0
 bra  _ListCall

 public LAutoScr_
LAutoScr_:
 moveq  #lAutoScroll,D0
 bra  _ListCall

 public LUpdate_
LUpdate_:
 moveq  #lUpdate,D0
 bra  _ListCall

 public LActivat_
LActivat_:
 moveq  #lActivate,D0
 bra  _ListCall

 end