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

C H A P T E R 1 6
Find
Using the Find Service 16-15
Although the implementation of a search method is for the most part application
specific, some general requirements apply to all search methods. This section
describes these requirements and advises you of potential problems your search
methods may need to handle.
Your search method must be able to search for data in internal RAM as well as in
RAM or ROM on a PCMCIA card. Using union soups, which allow you to treat
multiple soups as a single soup regardless of physical location, to store your data
makes it easier to solve this problem.
As a search method proceeds through the application data, it must test items
against criteria specified in the Find slip and collect the ones meeting the test
criteria. It also needs to call the
SetMessage method to provide a status string
that the system displays to the user while the search is in progress. Each of the
code examples included later in this section shows how to do this.
When the search is completed, it must append its finder frame to the system-
supplied
results array. This task is described in detail in “Returning Search
Results” (page 16-21).
If your application registers for participation in Global finds, your search methods
may be invoked when your application is not open. Thus, your search methods
must not rely on your application being open when they are invoked.
Using the StandardFind Method 16
You can use the system-supplied StandardFind method to search for text in
soup-based application data. This method makes the necessary calls to display the
status message, gather matching data items, and to append the finder frame that
contains the cursor with which to fetch found items to the system’s
results
array. The parameters are described in detail in “StandardFind” (page 13-13) in
Newton Programmer’s Reference.
You must call the GetUnionSoupAlways function, saving the result, before
calling StandardFind. Note that your Find method must be defined in your
application’s base view. Its use is illustrated in the following code example:
MyApplicationBase.Find :=
func(what, results, scope, statusView)
begin
// The following assignment forces the existence of
// a union soup. Always all GetUnionSoupAlways
//(saving the result in a local variable) before
// calling StandardFind.
local temp := GetUnionSoupAlways (kMySoupName);
:StandardFind(what, kMySoupName, results,
statusView, nil);
end;