Routing Interface

About Routing

In the user interface of your application, the Action button should be positioned
differently, depending on how your application displays individual items. If your
application can have more than one selectable item on the screen at a time (like
Notes), the Action button should be attached to the top of the view it will act on.
For example, each note in the Notes application has its own Action button, which
applies just to that note. If your application displays only one data item at a time,
the Action button must be on the status bar at the bottom of the screen.

You can add an Action button to the user interface of your application by adding a
view based on the

protoActionButton

proto. This proto contains the

functionality to create and pop up the picker.

The picker displayed when a user taps the Action button lists the routing actions
available for the particular type of data selected. There are two kinds of routing
actions that can appear on the Action picker:

routing actions that correspond to transports installed in the Newton device

application-defined actions that do not use the Out Box and a transport to
perform the routing operation, such as Delete and Duplicate

Transport-based actions that support the type of data being routed are shown at the
top of the Action picker. Application-defined routing actions appear at the bottom
of the picker, below a separator line.

Note that the first action listed in the Action picker has the name of the target item
appended to it (for example, "Print Note"). The Action picker obtains the name of
the item from the

appObject

slot. Most applications define this slot in their base

view. It holds an array of two strings, the singular and plural forms of the name of
the item (for example,

["Entry", "Entries"]

).

The system builds the list of routing actions dynamically, at the time the Action
button is tapped. This allows all applications to take advantage of new transports
that are added to the system at any time. Applications and transports need know
nothing about each other; the Routing interface acts as the bridge, creating the
picker at run time.

Applications don't specify that particular transports be included on the picker.
Instead, applications enable transports based on the class of data to route and the
types of formats available for that data class: for example, view formats (for printing
and faxing), frame formats (for beaming), text formats (for e-mail), and so on.

Here's a summary of the main steps that occur when the user taps the Action button:

1. The system obtains the target by sending the

GetTargetInfo

message to the

Action button view, and then determines the class of the target.

2. Using the class of the target, the system builds a list of routing formats that can

handle that class of data by looking them up in the view definition registry using
the

GetRouteFormats

function. Note that only routing formats are included

in the list; other view definitions are ignored.