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

C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects 11-37
▲
W A R N I N G
Each soup has only one tags index; if you add a tags index to a
soup that already has one, it replaces the original tags index. For
more information, see the description of the
AddIndexXmit
method (page 9-42) in Newton Programmer’s Reference. ▲
Removing Soups 11
When the user scrubs your application’s icon in the Extras Drawer, the system
sends a
DeletionScript message to your application. The DeletionScript
function is an optional function that you supply in your application’s form part.
This function accepts no arguments. You can remove your application’s soups from
within this function by invoking the
RemoveFromStoreXmit soup method. The
RemoveFromStoreXmit method is defined only for single soups; in other words,
you must remove each member of a union soup separately.
For more information on the DeletionScript method, see the Newton Toolkit
User’s Guide. See also “RemoveFromStoreXmit” (page 9-47) in Newton
Programmer’s Reference.
Do not delete soups from within your application’s viewQuitScript method—
user data needs to be preserved until the next time the application is run. For
similar reasons, do not remove soups from within your application’s
RemoveScript method. This method does not distinguish between removing
software permanently (scrubbing its icon in the Extras Drawer) and removing
software temporarily (ejecting the PCMCIA card.)
Using Built-in Soups 11
The soup-based data storage model makes it easy for applications to reuse existing
system-supplied soups for their own needs and to share their own soups with other
applications. Refer to Chapter 19, “Built-in Applications and System Data,” to see
descriptions of the soups used by the applications built into the Newton ROM. You
can also use these descriptions as a model for documenting the structure of your
application’s shared soups.
Making Changes to Other Applications’ Soups 11
You should avoid changing other applications’ soups if at all possible. If you must
make changes to another application’s soup, be sure to respect the format of that
soup as documented by its creator. When possible, confine your changes to a single
slot that you create in any soup entry you modify.
When naming slots you add to other applications’ soups, exercise the same caution
you would in naming soups themselves—use your application name and developer
signature in the slot name to avoid name-space conflicts.