Important: The information in this document is obsolete and should not be used for new development.
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 typeListHandle
. TheListRec
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 theLCellSize
procedure.visible
- Specifies the cells in a list that are visible within the area specified by the
rView
field. The List Manager sets theleft
andtop
fields ofvisible
to the coordinates of the first visible cell; however, the List Manager sets theright
andbottom
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 thevisible
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'sselFlags
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, orNIL
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
andtop
fields ofdataBounds
to the coordinates of the first cell in the list; the List Manager sets theright
andbottom
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 thedataBounds
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.