/*
**      Newton Developer Technical Support Sample Code
**
**      Status Report, a protoStatusTemplate and DoProgress example
**
**      by J. Christopher Bell and Bob Ebert, Newton Developer Technical Support
**
**      Copyright  1995 by Apple Computer, Inc.  All rights reserved.
**
**      You may incorporate this sample code into your applications without
**      restriction.  This sample code has been provided "AS IS" and the
**      responsibility for its operation is 100% yours.  You are not
**      permitted to modify and redistribute the source as "DTS Sample Code."
**      If you are going to re-distribute the source, we require that you
**      make it clear in the source that the code was descended from
**      Apple-provided sample code, but that you've made changes.
*/

This sample is intended to show three ways of implementing status and progress
to the user in the Newton 2.0 operating system.

Gauge:
	* a protoStatusTemplate sample showing a progress bar using the 'vGauge template
Barber:
	* a protoStatusTemplate sample showing a moving "barber pole" template. Use this
	  template if you want to make your own moving barber pole. Also, this is
	  implemented as a "custom" child template of protoStatusTemplate. If you want to
	  create your own child templates, use this as a guide.
DoProgress:
	* an example of how to use the DoProgress(...) function.
	
	
Most developers should use DoProgress(...) in their progress. Use DoProgress(...):
	* when your code is structured synchronously (that is, DoProgress does not return
	  until the workFunc function has completed or the user cancels the operation.) and
	* when you can use one of the built-in protoStatusTemplate types and
	* when the action is modal (the user cannot do anything until it is done 
	  or is canceled)
	
If any of these are not true, use protoStatusTemplate. Use protoStatusTemplate if:
	* your code is structured asychronously (it goes to the event loop).
	* your code uses communications (which might have asynchronous components).
	* your code requires a custom status template type. (possibly for a transport)
	* your actions are not modal (the user could proceed in your application or
	  other applications while the action is in progress)
	
	
About this sample:
The "action" functions are in base view, and called in repeated deferred
actions. The main "actions" which we fake are within the SaveWorld method and
the ComputeHalting method. When an action is "cancelled", the base view's
CancelRequest method is called, which sets a flag which is checked in the next
occurance of SaveWorld/ComputeHalting.

We override the application's close box to make sure actions are cancelled.
Although the application could close for other reasons (the application is
being made the background app, etc), overriding the close box in the
application allows us to warn most users who might accidentally quit the
application while actions are in progress. [the most recent version of the
platforms file temporarily requires that we set the _proto slot for
newtStatusNoClose in an afterScript ]

When the status slip is hidden, we are actually sending a Hide message to the
status view, not closing it. If another action is attempted while something is
in progress, an alert appears and the status view is re-shown. If the user
hides the status dialog, the show/hide scripts of the protoStatusTemplate that
we create will show/hide an "in progress" view which lets the user know that
actions are in progress although the status view is hidden.

Note that the DoProgress slip must have no close box.  You must do a little
extra to make this happen (see the example) but it is required.  (If not
present, the slip could be dismissed and the user could start interacting with
the application while the workFunc is still executing.  That is, the action
will no longer be modal, which could lead to crashing, bus errors, and other
bad behavior.)

The text in the "in progress view" is controlled by the same code which opens
the statusView. If your application is complicated, you might want to abstract
the InProgressView and statusView control codes into your base view.


List of files:
Resources - a ResEdit file which contains the pictures used in this sample.
MyStatusTemplate.f - a text file which contains a protoStatusTemplate definition.
	Includes an example of a custom status template (using the 'barber' pole 
	structure) and shows one way of storing your initial set up information
	used when you create your status view.
BaseView.t - our application template. The base view holds our action functions.
