Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) - Manual (Page 595)

C H A P T E R 1 6
Find
Using the Find Service 16-7
The only significant difference between a date find and a text find is that a different
search method locates the items that are returned. To support text searches, you
must supply a
Find method. To support searching by date, you must supply a
DateFind method.
You can support any of these search methods independently of one another; for
example, you can implement the
Find method without implementing the
DateFind method.
You may also customize searches by adding a subset of data items from one
application to the Selected picker menu in the Find slip. Items added here may be,
for instance, a checkbook and ledger from a personal finance program.
A finder is a frame that enumerates items resulting from a Find operation. The
general characteristics of your finder are defined by the proto it’s based on. The
system supplies two protos on which to base your finder: the
ROM_SoupFinder
or the ROM_CompatibleFinder .
The ROM_SoupFinder proto supports searching soup data. The
ROM_CompatibleFinder proto provides a framework, which you should
override, that supports searching data that is not soup based. When a finder based
on the
ROM_SoupFinder proto completes a search, it returns with a cursor which
is used to retrieve the found items from the application soup. When a finder based
on the
ROM_CompatibleFinder proto completes a search, it returns with the
actual found items in an array (the items array).
If you store data in soups, there are standard find methods defined for the
ROM_SoupFinder proto that you can use. When you devise a different scheme,
you must use the ROM_CompatibleFinder proto and define versions of the
finder methods that are tailored to your type of data storage.
After a search method scans your application’s data and returns a finder frame, you
must append it to the system-supplied
results array. Global and Selected finds
usually append more than one frame to this array, as multiple applications
complete their searches.
While a search continues, the system automatically provides user feedback on its
progress. When the search method completes, the system displays an overview list
of the items that were found.
For Global or Selected finds, each application (or data set, for a targeted data set
find) in which items were found is identified by a heading, with the found items
listed under it. The application name that appears in this heading is supplied by the
title slot each application provides in its base view.
The system sends a FindSoupExcerpt message to your application, which must
have a FindSoupExcerpt method to respond to it. This method must extract and
return a string for the Find overview to display. If no items are found, the
FindSoupExcerpt message is not sent. If you are using the