Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
Important: The information in this document is obsolete and should not be used for new development.
Summary of the List Manager
Pascal Summary
Constants
CONST {masks for listFlags field of list record} lDoVAutoScroll = 2; {allow vertical autoscrolling} lDoHAutoScroll = 1; {allow horizontal autoscrolling} {masks for selFlags field of list record} lOnlyOne = -128; {allow only one item to be selected at once} lExtendDrag = 64; {enable multiple item selection without Shift} lNoDisjoint = 32; {prevent discontiguous selections} lNoExtend = 16; {reset list before responding to Shift-click} lNoRect = 8; {Shift-drag selects items passed by cursor} lUseSense = 4; {allow use of Shift key to deselect items} lNoNilHilite = 2; {disable highlighting of empty cells} {messages to list definition procedure} lInitMsg = 0; {do any special list initialization} lDrawMsg = 1; {draw the cell} lHiliteMsg = 2; {invert cell's highlight state} lCloseMsg = 3; {take any special disposal action}Data Types
TYPE Cell = Point; {cell.v contains row number} {cell.h contains column number} DataArray = PACKED ARRAY[0..32000] OF Char; DataPtr = ^DataArray; DataHandle = ^DataPtr; ListRec = RECORD rView: Rect; {list's display rectangle} port: GrafPtr; {list's graphics port} indent: Point; {indent distance for drawing} cellSize: Point; {size in pixels of a cell} visible: Rect; {boundary of visible cells} vScroll: ControlHandle; {vertical scroll bar} hScroll: ControlHandle; {horizontal scroll bar} selFlags: SignedByte; {selection flags} lActive: Boolean; {TRUE if list is active} lReserved: SignedByte; {reserved} listFlags: SignedByte; {automatic scrolling flags} clikTime: LongInt; {TickCount at time of last click} clikLoc: Point; {position of last click} mouseLoc: Point; {current mouse location} lClikLoop: Ptr; {routine called by LClick} lastClick: Cell; {last cell clicked} refCon: LongInt; {for application use} listDefProc: {list definition procedure} Handle; userHandle: Handle; {for application use} dataBounds: Rect; {boundary of cells allocated} cells: DataHandle; {cell data} maxIndex: Integer; {used internally} cellArray: {offsets to data} ARRAY[1..1] OF Integer; END; ListPtr = ^ListRec; {pointer to a list record} ListHandle = ^ListPtr; {handle to a list record}List Manager Routines
Creating and Disposing of Lists
FUNCTION LNew (rView: Rect; dataBounds: Rect; cSize: Point; theProc: Integer; theWindow: WindowPtr; drawIt, hasGrow, scrollHoriz, scrollVert: Boolean): ListHandle; PROCEDURE LDispose (lHandle: ListHandle);Adding and Deleting Columns and Rows To and From a List
FUNCTION LAddColumn (count: Integer; colNum: Integer; lHandle: ListHandle): Integer; FUNCTION LAddRow (count: Integer; rowNum: Integer; lHandle: ListHandle): Integer; PROCEDURE LDelColumn (count: Integer; colNum: Integer; lHandle: ListHandle); PROCEDURE LDelRow (count: Integer; rowNum: Integer; lHandle: ListHandle);Determining or Changing the Selection
FUNCTION LGetSelect (next: Boolean; VAR theCell: Cell; lHandle: ListHandle): Boolean; PROCEDURE LSetSelect (setIt: Boolean; theCell: Cell; lHandle: ListHandle);Accessing and Manipulating Cell Data
PROCEDURE LSetCell (dataPtr: Ptr; dataLen: Integer; theCell: Cell; lHandle: ListHandle); PROCEDURE LAddToCell (dataPtr: Ptr; dataLen: Integer; theCell: Cell; lHandle: ListHandle); PROCEDURE LClrCell (theCell: Cell; lHandle: ListHandle); {the LGetCellDataLocation procedure is also available as the LFind procedure} PROCEDURE LGetCellDataLocation (VAR offset, len: Integer; theCell: Cell; lHandle: ListHandle); PROCEDURE LGetCell (dataPtr: Ptr; VAR dataLen: Integer; theCell: Cell; lHandle: ListHandle);Responding to Events Affecting Lists
FUNCTION LClick (pt: Point; modifiers: Integer; lHandle: ListHandle): Boolean; PROCEDURE LActivate (act: Boolean; lHandle: ListHandle); PROCEDURE LUpdate (theRgn: RgnHandle; lHandle: ListHandle);Modifying a List's Appearance
{the LSetDrawingMode procedure is also available as the LDoDraw procedure} PROCEDURE LSetDrawingMode(drawIt: Boolean; lHandle: ListHandle); PROCEDURE LDraw (theCell: Cell; lHandle: ListHandle); PROCEDURE LAutoScroll (lHandle: ListHandle); PROCEDURE LScroll (dCols: Integer; dRows: Integer; lHandle: ListHandle);Searching a List for a Particular Item
FUNCTION LSearch (dataPtr: Ptr; dataLen: Integer; searchProc: Ptr; VAR theCell: Cell; lHandle: ListHandle): Boolean;Changing the Size of Cells and Lists
PROCEDURE LSize (listWidth: Integer; listHeight: Integer; lHandle: ListHandle); PROCEDURE LCellSize (cSize: Point; lHandle: ListHandle);Getting Information About Cells
FUNCTION LNextCell (hNext: Boolean; vNext: Boolean; VAR theCell: Cell; lHandle: ListHandle): Boolean; PROCEDURE LRect (VAR cellRect: Rect; theCell: Cell; lHandle: ListHandle); FUNCTION LLastClick (lHandle: ListHandle): Cell;Application-Defined Routines
PROCEDURE MyLDEF (message: Integer; selected: Boolean; VAR cellRect: Rect; theCell: Cell; dataOffset: Integer; dataLen: Integer; theList: ListHandle); FUNCTION MyMatchFunction (cellDataPtr, searchDataPtr: Ptr; cellDataLen, searchDataLen: Integer): Integer; PROCEDURE MyClickLoop;C Summary
Constants
/*masks for listFlags field of list record*/ enum { lDoVAutoScroll = 2, /*allow vertical autoscrolling*/ lDoHAutoScroll = 1, /*allow horizontal autoscrolling*/ /*masks for selFlags field of list record*/ lOnlyOne = -128, /*allow only one item to be selected at once*/ lExtendDrag = 64, /*enable multiple item selection without Shift*/ lNoDisjoint = 32, /*prevent discontiguous selections*/ lNoExtend = 16, /*reset list before responding to Shift-click*/ lNoRect = 8, /*Shift-drag selects items passed by cursor*/ lUseSense = 4, /*allow use of Shift key to deselect items*/ lNoNilHilite = 2, /*disable highlighting of empty cells*/ /*messages to list definition procedure*/ lInitMsg = 0, /*do any special list initialization*/ lDrawMsg = 1, /*draw the cell*/ lHiliteMsg = 2, /*invert cell's highlight state*/ lCloseMsg = 3 /*take any special disposal action*/ };Data Types
typdef Point Cell; /*cell.v contains row number*/ /*cell.h contains column number*/ typedef char DataArray[32001], *DataPtr, **DataHandle; struct ListRec { Rect rView; /*list's display rectangle*/ GrafPtr ptr; /*list's graphics port*/ Point indent; /*indent distance for drawing*/ Point cellSize; /*size in pixels of a cell*/ Rect visible; /*boundary of visible cells*/ ControlHandle vScroll; /*vertical scroll bar*/ ControlHandle hScroll; /*horizontal scroll bar*/ char selFlags; /*selection flags*/ Boolean lActive; /*TRUE if list is active*/ char lReserved; /*reserved*/ char listFlags; /*automatic scrolling flags*/ long clikTime; /*TickCount at time of last click*/ Point clikLoc; /*position of last click*/ Point mouseLoc; /*current mouse location*/ ProcPtr lClikLoop; /*routine called by LClick*/ Cell lastClick; /*last cell clicked*/ long refCon; /*for application use*/ Handle listDefProc; /*list definition procedure*/ Handle userHandle; /*for application use*/ Rect dataBounds; /*boundary of cells allocated*/ DataHandle cells; /*cell data*/ short maxIndex; /*used internally*/ short cellArray[1]; /*offsets to data*/ }; typedef struct ListRect ListRect; typedef ListRect *ListPtr, **ListHandle;List Manager Routines
Creating and Disposing of Lists
pascal ListHandle LNew (const Rect *rView, Rect *dataBounds, Point *cSize, short theProc, WindowPtr theWindow, Boolean drawIt, Boolean hasGrow, Boolean scrollHoriz, Boolean scrollVert); pascal void LDispose (ListHandle lHandle);Adding and Deleting Columns and Rows To and From a List
pascal short LAddColumn (short count, short colNum, ListHandle lHandle); pascal short LAddRow (short count, short rowNum, ListHandle lHandle); pascal void LDelColumn (short count, short colNum, ListHandle lHandle); pascal void LDelRow (short count, short rowNum, ListHandle lHandle);Determining or Changing the Selection
pascal Boolean LGetSelect (Boolean next, Cell *theCell, ListHandle lHandle); pascal void LSetSelect (Boolean setIt, Cell theCell, ListHandle lHandle);Accessing and Manipulating Cell Data
pascal void LSetCell (const void *dataPtr, short dataLen, Cell theCell, ListHandle lHandle); pascal void LAddToCell (const void *dataPtr, short dataLen, Cell theCell, ListHandle lHandle); pascal void LClrCell (Cell theCell, ListHandle lHandle); /*the LGetCellDataLocation procedure is also available as */ /* the LFind procedure*/ pascal void LGetCellDataLocation (short *offset, short *len, Cell theCell, ListHandle lHandle); pascal void LGetCell (void *dataPtr, short *dataLen, Cell theCell, ListHandle lHandle);Responding to Events Affecting Lists
pascal Boolean LClick (Point pt, short modifiers, ListHandle lHandle); pascal void LActivate (Boolean act, ListHandle lHandle); pascal void LUpdate (RgnHandle theRgn, ListHandle lHandle);Modifying a List's Appearance
/*the LSetDrawingMode procedure is also available as the LDoDraw procedure*/ pascal void LSetDrawingMode (Boolean drawIt, ListHandle lHandle); pascal void LDraw (Cell theCell, ListHandle lHandle); pascal void LAutoScroll (ListHandle lHandle); pascal void LScroll (short dCols, short dRows, ListHandle lHandle);Searching for a List Containing a Particular Item
pascal Boolean LSearch (const void *dataPtr, short dataLen, SearchProcPtr searchProc, Cell *theCell, ListHandle lHandle);Changing the Size of Cells and Lists
pascal void LSize (short listWidth, short listHeight, ListHandle lHandle); pascal void LCellSize (Point cSize, ListHandle lHandle);Getting Information About Cells
pascal Boolean LNextCell (Boolean hNext, Boolean vNext, Cell *theCell, ListHandle lHandle); pascal void LRect (Rect *cellRect, Cell theCell, ListHandle lHandle); pascal Cell LLastClick (ListHandle lHandle);Application-Defined Routines
pascal void MyLDEF (short message, Boolean selected, Rect *cellRect, Cell theCell, short dataOffset, short dataLen, ListHandle theList); pascal short MyMatchFunction (Ptr cellDataPtr, Ptr searchDataPtr, short cellDataLen, short searchDataLen); pascal void MyClickLoop (void);Assembly-Language Summary
Data Structures
ListRect Data Structure
0 rView 8 bytes list's display rectangle 8 port long list's graphics port 12 indent 4 bytes indent distance for drawing 16 cellSize 4 bytes size in pixels of a cell 20 visible 8 bytes boundary of visible cells 28 vScroll long vertical scroll bar 32 hScroll long horizontal scroll bar 36 selFlags byte selection flags 37 lActive byte nonzero if list is active 38 lReserved byte reserved 39 listFlags byte automatic scrolling flags 40 clikTime long ticks at time of last click 44 clikLoc 4 bytes position of last click 48 mouseLoc 4 bytes current mouse location 52 lClikLoop long pointer to routine called by LClick56 lastClick 4 bytes last cell clicked 60 refCon long for application use 64 listDefProc long handle to code for list definition procedure 68 userHandle long for application use 72 dataBounds 8 bytes boundary of cells allocated 80 cells long handle to cell data 84 maxIndex word used internally 86 cellArray variable offsets to data Trap Macros
Trap Macros Requiring Routine Selectors
_Pack0