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

C H A P T E R 1 1
Data Storage and Retrieval
11-66 Using Newton Data Storage Objects
Your callback function must take any action that is appropriate to respond to the
change. Most applications have no need to respond to soup changes unless they are
open, which is why it is recommended that you register your callbacks when your
application opens and unregister them when it closes.
The arguments passed to your callback function include the name of the soup that
changed, the symbol identifying the callback function to execute, the kind of
change that occurred, and optional data such as changed soup entries. For a simple
code example, see “Registering Your Application for Change Notification”
beginning on page 11-64. For a complete description of the callback function and
its parameters, see the section “Callback Functions for Soup Change Notification”
(page 9-14) in Newton Programmer’s Reference.
▲
W A R N I N G
The 'soupEnters and 'soupLeaves messages are guaranteed
to be sent only when a reference to the changed soup exists. These
messages may not be sent for soups that are not in use. For
example, if no cursor object references the soup, this message
may not be sent.
▲
Sending Notifications 11
When your application alters a soup, it may need to notify other applications that
the soup has changed. The best means of doing so depends on the exact nature
of the change.
The system provides functions and methods that transmit change notification
messages automatically after altering soups, union soups, or entries. The names of
these auto-transmit routines end with the
-Xmit suffix. They are described
throughout this chapter in sections pertaining to the main behaviors they provide,
such as adding frames to soups as entries, changing entries, and so on.
The auto-transmit ( fnOrMethodName Xmit ) routines provide the easiest and best
way to send notifications when making a limited number of changes to a soup. For
example, to save a frame in a union soup and transmit an appropriate notification
message, use the
AddToDefaultStoreXmit method as shown in the following
code fragment:
// get soup in which to save the new entry
local myUSoup := GetUnionSoupAlways("myUSoup:mySig");
// frame to add as new entry
local myFrame := {name: Daphne, color: tabby};
// add the entry and transmit change notification
local ent := myUSoup:AddToDefaultStoreXmit(myFrame,'|MyApp:MySig|);
The auto-transmit methods and functions accept a changeSym parameter identifying
the application that changed the soup. If you pass nil for the value of the