---

Creating Custom Finders (2/5/96)

Q: My application uses more than one soup, so ROM_soupFinder is not appropriate, but ROM_compatibleFinder seems to throw many exceptions. Which should I use?

A: The answer depends on how much modification you will make. What you need is documentation on how they work and what you can override:

Each of the finder base protos (soupFinder and compatibleFinder) are magic pointers, so can create your own customizations at compile time.

So to do a soupFinder based item you could do something like:

DefConst('kMySoupFinder, {
    _proto: ROM_soupFinder,

    Delete: func()
    begin
        print("About to delete " & Length(selected) && "items") ;
        inherited:Delete() ;
    end,
}) ;

Most of these routines are only callable by your code. They should not be overwritten. Those routines that can be safely overriden are specified.

Some of methods and slots are common to both types of finders:

finder.selected

An array of selected items stored in an internal format. All you can do with this array is figure out the number of selected items by taking the Length of this array.

finder:Count()

Returns an integer with the total number of found items.

finder:ReSync()

Resets the finder to the first item.

finder:ShowFoundItem(item)

Displays the item passed. item is an overview item that resides in the
overview's items array.

finder:ShowOrdinalItem(ordinal)

Display an item based on the symbol or integer passed in ordinal:
'first - the first found item
'prev - the previous item
'next - the next item
<an-integer> - display the nth item based on the integer.

Under no circumstances should you call or override:

        finder:MakeFoundItem

        finder:AddFoundItems

ROM_SoupFinder

SoupFinder has the following methods and slots:

All the documented items from the simple use of soupFinder as documented in the Newton Programmer's Guide 2.0.

soupFinder:Reset()

Resets the soupFinder cursor to the first found entry. In general, you
should use the ReSync method to reset a finder.

soupFinder:ZeroOneOrMore()

Returns 0 if no found entries, 1 if one found entry or another number
for more than one entry.

soupFinder:ShowEntry(entry)

causes the finding application to display entry. This may involve
opening the application and moving it to that item.
This does not close the findOverview.

soupFinder:SelectItem(item)

mark the item as selected.
If this method is set to nil in the soupFinder proto, items will not have a checkbox in front of them (not selectable).

soupFinder:IsSelected(item)

Returns true if the item is selected.

soupFinder:ForEachSelected(callback)

Calls callback function with each selected item. The callback function has one argument, the entry from the soup cursor.

soupFinder:FileAndMove(labelsChanged, newLabel,
storeChanged, newStore)

File and/or move the selected items.
newLabel is the new label if and only if labelsChanged is true.
newStore is the new store if and only if storeChanged is true.

Developers can override this, though they may want to call the inherited routine to do that actual work. Note that FileAndMove can be called even if no items are selected. If you override this method you MUST check if there are selected items by doing:

    if selected then
        // do the work

soupFinder:FileAs(labels)

Deprecated. Do not use.

soupFinder:MoveTo(newStore)

Deprecated. Do not use.

soupFinder:Delete()

Deletes all selected items from read/write stores.

Developer can override. Note: if you override this, the crumple effect will
still happen. There is no way to prevent the ability to delete the items or
prevent the crumple effect at this time.

soupFinder:GetTarget()

Returns a cursor used by routing.

The following methods should not be called or modified:

    soupFinder.MakeFoundItem
soupFinder.AddFoundItems

ROM_CompatibleFinder

compatibleFinder:ShowFakeEntry(index)

Show the index'th item from the found items. Note that items will likely be an array of the found items.

ShowFakeEntry should behave just like ShowFoundItem. In other words, it should open the application then send a ShowFoundItem to the application.

compatibleFinder:ConvertToSoupEntry(item)

Return a soup entry that corresponds to the item. item is an item from the found items array.

The following methods are defined to be the same as the soupFinder:

        FileAs, MoveTo, Delete, IsSelected, SelectItem,
    ForEachSelected, GetTarget, FileAndMove

Note that this causes problems in some cases: most notably, the ForEachSelected call is expected to return an array of soup entries. The chances are you will need to override most of those methods. See soupFinder for a description of what the methods are supposed to do.