/* 
**      Newton Developer Technical Support Sample Code
**
**      Cardfile extensions, add stationery for Names application
**
**      by Tony Fang 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 shows several ways to extend the built in Names application (Cardfile). 
It shows two types of data that can be added via the "Add" menu, one which allows
only a single datum (social security number) and one which allows many items 
to be added (cars.)  It adds a new layout which will appear in the Show menu 
(showing the contents of the 'sorton slot.)  And finally it adds a whole new 
class of cards, available through the "New" menu, with editors and viewers 
and a new 'bizcard view.

Registering a viewDef for 'Add' menu.

	Any viewDef of type 'editor registered with a dataDefSym of 'person, 
		'company, or 'group will appear in then "Add" menu when a card of that 
		type is visible.  The sample has two. See the layout "Social Security 
		Stationery" for an example of a single item for 'person cards, and 
		"Cars Stationery" for an example of multiple items for 'person and 
		'company cards.
	The 'checkPaths and 'checkPrefix 'infoFrame slot in each stationery layout 
		is the one that controls whether a single or multiple items can be added.  
		Please note that when adding data to card file entries, your unique 
		(registered) signature must be used as part of the symbol name to avoid 
		conflicts with other developers and the Newton itself.
	Note that you can simply call RegisterViewDef several times (with 
		different dataDef symbols) to make the viewer available for 
		multiple card types.

Registering a new layout for all card types in the 'Show' menu.

	The "Sorton Layout" file contains a new layout which is intended to show up
		in the "Show" menu for the card file.  It's not strictly stationery in 
		the dataDef/viewDef sense, though it does contian elements of the 
		stationery data.  Instead, this is actually a layout view from the 
		newtLayout layer of the structure.
	This new layout is added to the cardfile with a method cardfile:AddLayout.
		It is removed with a platform file function, kCardFileSafeRemoveLayoutFunc. 
		It is important to use the platform file version of the function instead 
		of using cardfile:RemoveLayout.  (You can render the card file unusable 
		if you use the card file method directly.)
   	Note that these layouts must work for any card type, since the contents of the
   		show menu are visible for all cards.  You should make sure that at least
   		some of the common fields in the Names entries are visible, so that you won't
   		end up with a completely blank layout.

Registering a dataDef for a new card type 'New' menu.
	The "Car DataDef" layout contains a stationery datadef for a new card type,
		one to track cars.  It's registered with the standard RegDataDef call.
	The layout "Car Name ViewDef" provides the default editor for the data, 
		which will be the name of the car.
	"Car Make/Model ViewDef" provides an additional piece of data which can
		be entered.  Note how the infoFrame for this viewDef differs from the
		make/model definition for 'person and 'company cards.  For a car card,
		only a single make/model item is allowed, and the data for that item
		is stored at the "top level" of the soup entry.
	The "Car Bizcard ViewDef" provides the simple "Card" view for Car cards.  
		It's very simple.
	In order for the "All Info" view to work with a new card, we must provide
		some viewDef that is appropriate for that viewer.  The best way to do
		this is simply to steal the All Info view that the card file provides
		for the other card types.  The internals of this viewDef are
		undocumented, so simple get a reference to it 
		(GetViewDefs('person).allInfo) and register it for your own dataDef symbol.

Special Note on 'bizCard viewDefs.  BizCards are distinguished by a number,
in the 'bizCardNum slot of the viewDef.  That same number is stored in the
soup entry.  Because this isn't a symbol, there is potential for conflict.

If you wish to create a new bizCard type and guarantee it's number, start
with an integer greater than 1000 and register the number with the DTS group
via the NEWTONDEV AppleLink address or the most recent equivalent.  
(See Signature Registration Guidelines for details.)
