Find

Using the Find Service

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