![]() |
ListSearchProcPtr |
||||
Header: | Lists.h | Carbon status: | Supported | |
Defines a pointer to a list search callback function. Your list search callback function compares data in a search field to the contents of a list cell.
typedef SInt16(* ListSearchProcPtr) ( Ptr aPtr, Ptr bPtr, SInt16 aLen, SInt16 bLen );
You would declare your function like this if you were to name it MyListSearchCallback:
SInt16 MyListSearchCallback ( Ptr aPtr, Ptr bPtr, SInt16 aLen, SInt16 bLen );
A pointer to the data contained in a cell.
A pointer to the data for which you are searching.
The number of bytes of data contained in the cell.
The number of bytes of data for which you are searching.
If the cell data matches the search data, your function should return 0. Otherwise, your search function should return 1.
You can pass a pointer to your search function as the third parameter to the LSearch function. A search function must compare the data defined by the aPtr and aLen parameters with the data defined by the bPtr and bLen parameters. Your function can use any technique you choose to compare the data.
If you do not wish to create your own search function, your application can specify NULL as a parameter to LSearch, in place of a pointer to your function. LSearch then uses the Text Utilities function IUMagIDString, the default search function. The IUMagIDString function returns 0 if the search data exactly matches the cell data, but IUMagIDString considers the strings 'Rose' and 'rosé' to be equivalent. If your application simply needs a search function that works like IUMagIDString but considers 'Rose' to be different from 'rosé', the Text Utilities provides the case-sensitive comparison function IUMagString. Instead of writing a custom function, your application can simply pass @IUMagString as the third parameter to the LSearch function.
The pointer which you pass to the LSearch function should be a universal procedure pointer (UPP). The definition of the UPP data type for your search function is as follows:
typedef (ListSearchProcPtr) ListSearchUPP;
Before using your search function, you must first create a universal procedure pointer to it, using the NewListSearchUPP NewListSearchUPP function, as shown here:
ListSearchUPP MyListSearchUPP;
MyListSearchUPP = NewListSearchUPP(&MyListSearchProc);
You then pass MyListSearchUPP to the LSearch function, which will call your custom search function on each cell it searches. If you wish to call your own list search function, use the InvokeListSearchUPP function:
isMatch = InvokeListSearchUPP(aPtr, bPtr, aLen, bLen, MyListSearchUPP);
When you are finished with your list search callback function, you should dispose of the universal procedure pointer associated with it, using the DisposeListSearchUPP function:
DisposeListSearchUPP(MyListSearchUPP);
A search function does not execute at interrupt time. Instead, it is called directly by the LSearch function. Thus, a search function can allocate memory, and it does not need to adjust the value contained in the A5 register.
A search function does not execute at interrupt time. Instead, it is called directly by the LSearch function. Thus, a search function can allocate memory, and it does not need to adjust the value contained in the A5 register.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)