Find

Using the Find Service

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;