![]() |
ListDefProcPtr |
||||
Header: | Lists.h | Carbon status: | Supported | |
Defines a pointer to a list definition callback function. Your list definition callback function defines a custom list display.
typedef void(* ListDefProcPtr) ( SInt16 lMessage, Boolean lSelect, Rect *lRect, Cell lCell, SInt16 lDataOffset, SInt16 lDataLen, ListHandle lHandle );
You would declare your function like this if you were to name it MyListDefCallback:
void MyListDefCallback ( SInt16 lMessage, Boolean lSelect, Rect *lRect, Cell lCell, SInt16 lDataOffset, SInt16 lDataLen, ListHandle lHandle );
A value that identifies the operation to be performed. See
Indicates whether the cell specified by the lCell parameter should be highlighted. This parameter is defined only for the lDrawMessage and lHiliteMsg messages.
A pointer to the rectangle (in local coordinates of the lists graphics port) that encloses the specified cell. Although this parameter is defined as a pointer, your list definition function must not change the coordinates of the rectangle. This parameter is defined only for the lDrawMessage and lHiliteMsg messages.
The coordinates of the cell to be drawn or highlighted. This parameter is defined only for the lDrawMessage and lHiliteMsg messages.
The location of the cell data associated with the specified cell. 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.
The length in bytes of the cell data associated with the specified. This parameter is defined only for the lDrawMessage and lHiliteMsg messages.
A handle to the list for which a message is being sent. Your application can access the lists list record, or it can call List Manager functions to manipulate the list.
Your application can write a list definition function to customize list display. For example, you can write a list definition function to support the display of color icons. A custom list definition function must be compiled as a code resource of type 'LDEF' and added to the resource file of the application that needs to use it.
The List Manager calls your list definition function whenever an application using the function creates a new list with the LNew function, needs a cell to be drawn, needs a cells highlighting state to be reversed, or has called the LDispose function to dispose of a list.
The pointer to your list definition function should be a universal procedure pointer (UPP). The definition of the UPP data type for your definition function is as follows:
typedef (ListDefProcPtr) ListDefUPP;
Before using your list definition function, you must first create a new universal procedure pointer to it, using the NewListDefUPP function, as shown here:
ListDefUPP MyListDefUPP;
MyListDefUPP = NewListDefUPP(&MyListDefProc);
The List Manager automatically invokes your list definition function when a new list is created. If you wish to call your own list definition callback function, you can use the InvokeListDefUPP function:
InvokeListDefUPP(lMessage, lSelect, &lRect, lCell, lDataOffset, lDataLen, lHandle, MyListDefUPP);
When you are finished with your list definition function, you should dispose of the universal procedure pointer associated with it, using the DisposeListDefUPP function.
DisposeListDefUPP(MyListDefUPP);
Because a list definition function 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 systems documentation for more information.) If your list definition function 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.
Because a list definition function 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 systems documentation for more information.) If your list definition function 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.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)