/*  
**      Newton Developer Technical Support Sample Code
**
**      AutoRoute, an example of the Newton 2.0 Send function.
**
**      by J. Christopher Bell, Newton Developer Technical Support
**
**      Copyright  1995-1996 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.
*/

=== About this sample

This sample code illustrates how you can mail, print, fax, and beam without a
protoActionButton in Newton 2.0 OS. It does so using the Send function to send
data to the user (using the current Persona setting, modifyable at the top of
the application) with one of the installed transports. For instance, if the
persona is set to your work persona, using AutoRoute to fax will fax an item to
your fax machine at work (based on your Owner Info information).

The code for preparing data for the Send function is in the AutoRoute method
of the base view. That is the code you probably want to browse.

Most of the user interface is designed to set up the item slots. This sample
is NOT intended to recommend a particular user interface for applications
using the Send function. This is only an example; yours will be prettier...

These are the base view slots that the user interface sets up: 
	transportSym	- the symbol of the currently chosen transport
	formatSym		- the symbol of the currently chosen format
	sendNow			- send immediately (true or nil)
	currentPrinterSetting - a printer frame (set in Print Options)

The code that prepares the popups of transports and formats are in the
pickerSetup methods of the respective pickers. The labelActionScript of
each picker sets the base view slots transportSym and formatSym.


=== About using Send

First, you must create an item with:
   Transport(transportSym, 'NewItem, [nil]);

Then, set up your basic item slots like:
	body			- the data itself
	title			- the title in the I/O Box
	appSymbol		- the owner, used for Put Away in frame-based transports
                	  (for instance, beam and mail with attachments)
	currentFormat   - the symbol of the current Route Format
	toRef			- the recipients of of the item (an array of "nameRef"
					  objects, used by protoListPicker-based views)
	
There also are optional slots. The ones used in this sample are:
	connect			- "send immediately" -- might be ignored
	printer			- the current printer (used by Print)

There are MANY other item slots. Some apply to all transports (like
the 'hidden slot) and some apply ONLY apply to certain transports (like
the phoneNumber slot or the saveAsLog call transport slot).

Although it is not a complete list of item slots, there are many item 
slots listed in the Routing Interface chapter of the Newton Programmers 
Guide (NPG) Communications manual.


=== Other notes

This sample also shows how to use the protoPrinterChooserButton properly.
This protoPrinterChooserButton is somewhat unusual in that it modifies 
a "global" setting in the userConfiguration frame. This sample shows how
to get and set these settings using GetUserConfig and SetUserConfig.

Because this proto modifies a global setting, if you use it to modify an
application-specific printer choice, you should open a view based on
printerChooserButton only when necessary. Otherwise, you could seriously
interfere with other applications that get or set the currentPrinter. Note that
you can save the printer frame in a soup but do not try to look at or modify
slots in this frame. The only supported way of getting a printer frame is to
get it using the code "GetUserConfig('currentPrinter)". Check the Platform File
Notes documentation for more information. If you need to display the printer
name, check out the GetPrinterName function in the Platform File Notes.

The Printer Options button only appears when the print transport is selected.
When the Printer Options button receives the NewTransportChosen message, it
sends itself the Hide or Show message as appropriate.

===== Known bugs

* In Newton 2.0 OS, the protoPrinterChooserButton modifies a system-wide setting. 
  To use it to modify an application-specific printer choice, you must use 
  GetUserConfig and SetUserConfig (see the PrintChooser layout for more info).
* When sending to the Print transport in Newton 2.0 OS, if an item.toRef slot is
  present, some user interface elements show "fax" information. For instance,
  the status dialog might also contain a phone number, and some error dialogs
  will mention the word "fax" erroneously.


J. Christopher Bell
Feb 13, 1996
Newton Developer Technical Support
