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

C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects 11-33
Registering and Unregistering Soup Definitions 11
The RegUnionSoup global function registers a soup definition with the system
and returns a union soup object to which you can send messages. Once the soup
definition is registered, various union soup methods create the union’s member
soups as needed to save entries. A corollary function,
UnRegUnionSoup ,
unregisters a specified soup definition.
You can register a soup definition with the system any time before your application
needs to access the soup it defines. If your application is the only one using your
soup, you need only ensure that its definition is registered while the application is
actually open. Normally, code that registers soup definitions is provided by your
application part’s
InstallScript function or your application base view’s
ViewSetupFormScript method. You need not be concerned with registering a
soup definition twice as long as you don’t register different soup definitions that
have the same name.
Code to unregister soup definitions is usually provided either by your application
base view’s
ViewQuitScript method (to unregister when the application closes)
or your application part’s DeletionScript function (to unregister only when the
application is removed.) An application that allows the user to file or move data
items from the Extras Drawer should allow its soup definitions to remain registered
while the application is closed, unregistering them only when the application is
removed. For more information on manipulating soup entries from the Extras
Drawer, see “About Icons and the Extras Drawer” on page 19-38 in Chapter 19,
“Built-in Applications and System Data.”
Your application can also call the RegUnionSoup function to retrieve its own
union soups that already exist. If you call RegUnionSoup on a soup definition
that is already registered, this function replaces the currently registered soup
definition with the new one and returns the union soup named by the soup
definition passed as its argument; if that union soup does not exist, this method
uses the soup definition passed as its argument to create a new union soup that it
returns. Alternatively, you can call the
GetUnionSoupAlways global function to
retrieve any extant union soup, not just those your application registers. For more
information, see “Retrieving Existing Soups” beginning on page 11-34.
To use the RegUnionSoup function, you might put code like the following
example in the ViewSetupFormScript method of your application’s base view:
local mySoupDef := {name: "mySoup:mySig",
userName: "My Soup",
ownerApp: '|MyApp:MySig|,
ownerAppName : "My Application",
userDescr: "This is the My Application soup.",