Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 4 - List Manager / List Manager Reference

Data Structures

The List Record

The List Manager uses a list record to store many types of information about a list. Usually you access a list record through a handle to the list record defined by the data type ListHandle. The ListRec data type defines a list record.

TYPE 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}

Field Description

rView

Specifies the rectangle in which the list's visible rectangle is located, in local coordinates of the graphics port specified by the port field. Note that the list's visible rectangle does not include the area needed for the list's scroll bars. The width of a vertical scroll bar (which equals the height of a horizontal scroll bar) is 15 pixels.

port

Specifies the graphics port of the window containing the list.

indent

Defines the location, relative to the upper-left corner of a cell, at which drawing should begin. List definition procedures should set this field to a value appropriate to the type of data that a cell in a list is to contain.

cellSize

Contains the size in pixels of each cell in the list. When your application creates a list, it can either specify the cell size or let the List Manager calculate the cell size. You should not change the cellSize field directly; if you need to change the cell size after creating a list, use the LCellSize procedure.

visible

Specifies the cells in a list that are visible within the area specified by the rView field. The List Manager sets the left and top fields of visible to the coordinates of the first visible cell; however, the List Manager sets the right and bottom fields so that each is 1 greater than the horizontal and vertical coordinates of the last visible cell. For example, if a list contains 4 columns and 10 rows but only the first 2 columns and the first 5 rows are visible (that is, the last visible cell has coordinates (1,4)), the List Manager sets the visible field to (0,0,2,5).

vScroll

Contains a control handle for a list's vertical scroll bar, or NIL if a list does not have a vertical scroll bar.

hScroll

Contains a control handle for a list's horizontal scroll bar, or NIL if a list does not have a vertical scroll bar.

selFlags

Indicates the selection flags for a list. When your application creates a list, the List Manager clears the selFlags field to 0. This defines the List Manager's default selection algorithm. To change the default behavior for a particular list, set the desired bits in the list's selFlags field.

You can use these constants to refer to bits in this field:

               CONST 
                  {allow only one item to be selected at once}
                  lOnlyOne       = -128;
                  {enable multiple item selection without Shift}
                  lExtendDrag    = 64;
                  {prevent discontiguous selections}
                  lNoDisjoint    = 32;
                  {reset list before responding to Shift-click}
                  lNoExtend      = 16;
                  {Shift-drag selects items passed by cursor}
                  lNoRect        = 8;
                  {allow use of Shift key to deselect items}
                  lUseSense      = 4;
                  {disable highlighting of empty cells}
                  lNoNilNilite   = 2;

lActive

Indicates whether the list is active (TRUE if active, FALSE if inactive).

lReserved

Reserved.

listFlags

Indicates whether the List Manager should automatically scroll the list if the user clicks the list and then drags the cursor outside
the list display rectangle.

The following constants define bits in this field that determine whether horizontal autoscrolling and vertical autoscrolling are enabled:

               CONST
                  {allow automatic vertical scrolling}
                  lDoVAutoscroll    = 2;
                  {allow automatic horizontal scrolling}
                  lDoHAutoscroll    = 1;

By default, the List Manager enables horizontal autoscrolling for a list if the list includes a horizontal scroll bar, and enables vertical autoscrolling for a list if the list includes a vertical scroll bar.

clikTime

Specifies the time in ticks of the last click in the list. If your application depends on the value contained in this field, then
your application should update the field should the application select a list item in response to keyboard input.

clikLoc

Specifies the location in local coordinates of the last click in the list.

mouseLoc

Indicates the current location of the cursor in local coordinates. This value is continuously updated by the LClick function after the user clicks a list.

lClikLoop

Contains a pointer to a click-loop procedure repeatedly called by the LClick function, or NIL if the default click-loop procedure is to be used. For information on click-loop procedures, see "Click-Loop Procedures" beginning on page 4-90.

lastClick

Specifies the coordinates of the last cell in the list that was clicked. This may not be the same as the last cell selected if the user selects a range of cells by Shift-dragging or Command-dragging. If your application depends on the value contained in this field, then
your application should update the field whenever your application selects a list item in response to keyboard input.

refCon

Contains 4 bytes for use by your application.

listDefProc

Contains a handle to the code for the list definition procedure that defines how the list is drawn.

userHandle

Contains 4 bytes that your application can use as needed. For example, your application might use this field to store a handle to additional storage associated with the list. However, the LDispose procedure does not automatically release this storage when disposing of the list.

dataBounds

Specifies the range of cells in a list. When your application creates a list, it specifies the initial bounds of the list. As your application adds rows and columns, the List Manager updates this field. The List Manager sets the left and top fields of dataBounds to the coordinates of the first cell in the list; the List Manager sets the right and bottom fields so that each is 1 greater than the horizontal and vertical coordinates of the last cell. For example, if a list contains 4 columns and 10 rows (that is, the last cell in the list has coordinates (3,9)), the List Manager sets the dataBounds field to (0,0,4,10).

cells

Contains a handle to a relocatable block used to store cell data. Your application should not change the contents of this relocatable block directly.

maxIndex

Used internally.

cellArray

Contains offsets to data that indicate the location of different cells' data within the data handle specified by the cells parameter. Your application should not access this field directly.