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

C H A P T E R 1 1
Data Storage and Retrieval
11-60 Using Newton Data Storage Objects
When the frame is constructed from the entry, it is cached in memory. At this point,
you can add, modify, and delete slots just as you would in any other frame;
however, the changes do not persist until the
EntryChangeXmit function is
called for that particular entry. The EntryChangeXmit function writes the cached
entry frame back to the soup, replacing the original entry with the changed one.
If the EntryUndoChangesXmit function is called, the changes are thrown out
and the entry is restored to its original state. This function disposes of the cached
entry frame and restores the reference to the original uncached entry, just as if the
original entry was never referenced. Note that you can use the
FrameDirty
function to determine whether a cached entry has been modified since it was read
into the NewtonScript heap; however, this function does not detect changes to
individual characters in a string (a common operation for
clParagraphView
views). For more information, see “FrameDirty” (page 9-69) in Newton
Programmer’s Reference.
The following code example gets an entry from the namesUSoup union soup,
changes it, and writes the changed entry back to the soup:
local namesUSoup := GetUnionSoupAlways(ROM_CardFileSoupName);
local namesCursor := namesUSoup:Query(nil);
local theEntry := namesCursor:Entry();
if theEntry then
begin
theEntry.cardType := 4;
EntryChangeXmit(theEntry, '|MyApp:MySig|);
end;
It’s not always easy to determine the best time to write a cached entry back to its
soup. For example, it would be inappropriate to call a function like
EntryChangeXmit from the ViewChangedScript method of a
protoLabelInputLine view. When the user enters data on the input line with
the keyboard, the ViewChangedScript is called after every key press. Calling
the EntryChangeXmit function for every key press would be noticeably slow.
In some situations, the appropriate time to call EntryChangeXmit is more
obvious. For example, a natural time to call EntryChangeXmit would be when
the user dismisses an input slip.
Moving Entries 11
You can use the MoveTarget method of the root view to move (not copy) an
entry into the same-named soup on another store. For example, you would use
this method to move entries from one union soup member to another. For more
information, see “System-Supplied Filing Methods” (page 12-11) in Newton
Programmer’s Reference.