Additional System Services

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.