Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 4 - List Manager / List Manager Reference

Application-Defined Routines / List Definition Procedures

MyLDEF

A list definition procedure has the following syntax:

PROCEDURE MyLDEF (message: Integer; selected: Boolean; 
                  VAR cellRect: Rect; theCell: Cell; 
                  dataOffset: Integer; dataLen: Integer;
                  theList: ListHandle);

message

A value that identifies the operation to be performed. These constants specify the four types of messages:

            CONST 
               lInitMsg    = 0;  {do any special initialization}
               lDrawMsg    = 1;  {draw the cell}
               lHiliteMsg  = 2;  {invert cell's highlight state}
               lCloseMsg   = 3;  {do any special disposal action}

selected

A Boolean value that indicates whether the cell specified by the theCell parameter should be highlighted. This parameter is defined only for the lDrawMessage and lHiliteMsg messages.

cellRect

The rectangle (in local coordinates of the list's graphics port) that encloses the cell specified by the theCell parameter. Although this parameter is defined as a VAR parameter, your list definition procedure must not change the coordinates of the rectangle. This parameter is defined only for the lDrawMessage and lHiliteMsg messages.

theCell

The coordinates of the cell to be drawn or highlighted. This parameter is defined only for the lDrawMessage and lHiliteMsg messages.

dataOffset

The location of the cell data associated with the cell specified by the theCell parameter. The location is specified as an offset from the beginning of the relocatable block referenced by the cells field of the list record. This parameter is defined only for the lDrawMessage and lHiliteMsg messages.

dataLen

The length in bytes of the cell data associated with the cell specified by the theCell parameter. This parameter is defined only for the lDrawMessage and lHiliteMsg messages.

theList

The list for which a message is being sent. Your application can access the list's list record, or it can call List Manager routines to manipulate the list.

DESCRIPTION

The List Manager calls your list definition procedure whenever an application using the procedure creates a new list with the LNew function, needs a cell to be drawn, needs a cell's highlighting state to be reversed, or has called the LDispose procedure to dispose of a list.

In response to the lInitMsg message, your list definition procedure should perform any special initialization needed for a list. For example, the procedure might set fields of the list record, such as the cellSize and indent fields, to appropriate values. Your list definition procedure does not necessarily need to do anything in response to the initialization message. If it does nothing, then memory is still allocated for the list, and fields of the list record are set to the same values as they would be set to if the default list definition procedure were being used. (For more information on those values, see "About the List Manager" beginning on page 4-13.)

Your list definition procedure should draw the cell specified by the theCell parameter after receiving an lDrawMsg message. The procedure must ensure that it does not draw anywhere but within the rectangle specified by the cellRect parameter. If the selected parameter is TRUE, then your list definition procedure should draw the cell in its highlighted state; otherwise, it should draw the cell without highlighting. When drawing, your list definition procedure should take care not to permanently change any characteristics of the drawing environment.

Your list definition procedure should respond to the lHiliteMsg message by reversing the selection status of the cell contained within the rectangle specified by the cellRect parameter. If a cell is highlighted, your list definition procedure should remove the highlighting; if a cell is not highlighted, your list definition procedure should highlight it.

The List Manager sends your list definition procedure an lCloseMsg message before it disposes of a list and its data. Your list definition procedure need only respond to this message if additional memory has been allocated for the list. For example, your list definition procedure might allocate a relocatable block in response to the lInitMsg message. In this case, your list definition procedure would need to dispose of this relocatable block in response to the lCloseMsg message. Or, if your list definition procedure defines cells simply to contain pointers or handles to data stored elsewhere in memory, it would need to dispose of that memory in response to the lCloseMsg message.

SPECIAL CONSIDERATIONS

You must compile a list definition procedure as a resource of type 'LDEF' before it can be used by an application.

Because a list definition procedure is stored in a code resource, it cannot have its own global variables that it accesses through the A5 register. (Some development systems, however, may allow code resources to access global variables through some other register, such as A4. See your development system's documentation for more information.) If your list definition procedure needs access to global data, it might store a handle to such data in the refCon or userHandle fields of the list record; however, applications would not then be able to use these fields for their own purposes.

ASSEMBLY-LANGUAGE INFORMATION

The entry point of a list definition procedure must be at the beginning.

SEE ALSO

For an example of a list definition procedure, see "Writing Your Own List Definition Procedure" beginning on page 4-49.