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

C H A P T E R 2 1
Routing Interface
21-12 Using Routing
If your application does not have a lastFormats slot, or if a matching format
is not found (the format was unregistered), the first format found becomes the
current format.
It is your responsibility to save the lastFormats frame to a soup if you want to
maintain it, since this information is cleared on a system reset or if your application
is uninstalled.
Supplying the Target Object 21
Next, the Routing interface sends the SetupItem message to the current format.
This message informs the format that it is selected and an item is being routed. The
SetupItem method is passed two parameters: a partially initialized item frame,
and a target information frame, as returned by GetTargetInfo . The item frame
is obtained from the transport method NewItem , which creates a new Out Box
item frame containing some default slots and values. This is the frame that is to be
stored in the Out Box. It must be filled in with the data object being sent.
The target information frame contains two important slots, target and
targetView , which define the data object to be routed and the view that contains
it, respectively. The SetupItem method must set the body slot of the item frame
to the value contained in the target slot of the target information frame. This fills
in the item frame with the actual data to be sent.
You are not required to provide a SetupItem method in routing formats since this
method is defined in the routing format protos. The SetupItem method defined in
the protos simply assigns the target slot in the target information frame to the
body slot of the item frame. You can override this method if you want to perform
additional operations and still call the inherited SetupItem method. Note that
there’s a potential problem with not copying the target object. If the object is
viewable and editable and the user edits the object in the Out Box, that potentially
changes the original object stored by the application, since there are potentially not
two separate objects, but two pointers to the same object.
If you want to modify the body slot of the item in some way, you should supply
your own SetupItem method instead of calling the inherited version. Then
in your own SetupItem method, clone the target slot of the target information
frame into the body slot of the item frame.
When sending data to another Newton device (for example, by beaming) it’s a
good idea to ensure that the sent object contains a
version slot (inside the
item.body frame) that holds the current version of your application. This will help
to reduce compatibility problems in future versions of your application. If the data
format changes, your application can easily identify older and newer data formats.