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

C H A P T E R 1 7
Additional System Services
17-18 Using Additional System Services
The code above shows the two ways in which your code can respond when the user
cancels the operation. If the user taps the Stop button an exception is thrown by
SetStatus . You may catch this exception and perform any clean-up necessary.
(In the code above the all-inclusive |evt.ex| onexception clause catches this
exception.) You must, however, rethrow this exception so the system can perform
its own cleanup, otherwise the Newton device appears to hang. You must ensure
that any exceptions you do not specifically anticipate are rethrown by your
exception-handling code.
You may also perform any necessary housecleaning after an uncompleted operation
by comparing the result of the
DoProgress function. If the user tapped the Stop
button, DoProgress returns the symbol 'cancelled .
Using DoProgress or Creating Your Own protoStatusTemplate 17
The DoProgress function creates a view based on the protoStatusTemplate
to report progress to the user. Using this function is the simplest way to create a
protoStatusTemplate view. However, it is not suitable for all applications.
You should use DoProgress if
■ Your code is structured synchronously; that is, DoProgress does not return
until the workFunc function has completed or the user cancels the operation.
■ The built-in bar gauge or barber pole status slips which DoProgress uses are
suitable for your needs.
■ The action is modal; that is, the user cannot do anything until the action finishes
or is canceled.
If any of these is not true, use protoStatusTemplate ; that is you should create
your own protoStatusTemplate if
■ Your code is structured asynchronously; that is, it allows user events to be
processed normally.
■ Your code uses communications; these usually have asynchronous components.
■ Your code requires a custom status template type; possibly for a transport.
■ Your actions are not modal; that is, the user could proceed in your application or
other applications while the action is in progress.
Using protoStatusTemplate Views 17
You need to take the following steps to use a protoStatusTemplate view to
report progress to the user:
1. Specify the components of the status slip and their initial values. You can use
one of the system-supplied templates or create your own template.