/*
**      Newton Developer Technical Support Sample Code
**
**      PreeferMadnessTNG, How to do preferences for your application
**
**      by Maurice Sharp and David Fedor, Newton Developer Technical Support
**
**      Copyright © 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.
*/

Once upon a time there was a sample called PreeferMadness. This sample showed
you everything you need to do for preferences and formulas. It even provided
you with protos for pref items. Then Newton 2.0 OS came along.

So here is PreeferMadnessTNG (The Next Generation). Like its elder, it shows
you all you need to know for preferences and formulas. But now it does it the
Newton 2.0 OS way.


Application Preferences
-----------------------
Preferences for your application are accessed through the "Prefs" item in a
protoInfoButton. The code that implements this is in PreeferMadness.t. The
info button is in the menuLeftButtons array of the newtStatusBar. The
method to open the prefs slip is in MyBase.DoInfoPrefs.

Once the user taps on the Prefs item, what you bring up depends on how
many preferences your application has.

If all of your prefs can be logically grouped into one slip, then you
should bring up your prefs inside a protoFloatNGo. The slip must have a
title (protoTitle) that is "<app-name> Preferences". It should be centered
in your application base view. For an example see the Names application
preferences.  This is demonstrated here in PreeferSinglePrefFloater.t.

If you need more than one logical grouping, bring up a floating overview of
your preference choices. This sample provides you with a user proto
template called protoPrefsOverview that you can use as the basis of your
preferences overview. This is similar to the Prefs application in Extras,
and is demonstrated in PreeferMultiplePrefsOverview.t.

If you use protoPrefsOverview, each preference panel (i.e., grouping of
logically related preferences) must use a protoPrefsRollItem as the base
view. See PreeferAppPrefsItems or PreeferPhilPrefItem for examples.

If you have a single preference, this sample expects the panel to be based
on protoPrefsRollItem. If you do not want to use that proto, you will be
responsible for providing the correct UI.

Remember that you can use GetAppPrefs to get your application preferences
frame. The frame returned by that call is a soup entry, so you can use
EntryChange to update changes to your preferences.


System Preferences
------------------
PreeferMadnessTNG also shows you how to add something to the system
preferences. Note that nearly no applications need to do this. The only
reason to do this is if you are an auto part that requires preferences and
can not set them through some system provided mechanism (e.g., transports
use the I/O box Prefs item).

Adding the preference is easy. See the InstallScript and RemoveScript
inside PackageStuff.t. The preference panel itself (PreeferAutoPrefsItem)
is also based on protoPrefsRollItem.

Note that unlike an application preference, your system preference must
have an appropriate icon. See the icon slot in the base view of
PreeferAutoPrefsItem. Notice that this icon is smaller than those used for
your application. It should be no larger than 14 x 12. At that size it may
look a little wierd. Experiment, have fun, but make it meaningful.


Formulas
--------
Adding a formula is straightforward. See the InstallScript and RemoveScript
inside PackageStuff.t. PreeferMadnessTNG provides the PreeferFormulaItem
user proto that you can easily adapt for your own formula items.


Roadmap
-------
Here's a partial "roadmap" showing what view contains (or opens) what other
view(s), since there are a bunch of files in this sample.

  PreeferMadness.t                                application base view

    PreeferSinglePrefFloater.t                   contains one pref slip
        PreeferAppPrefsItems                       is the app pref slip

    PreeferMultiplePrefsOverview.t           overview of multiple slips
        PreeferAppPrefsItems                            is pref slip #1
        PreeferPhilPrefItem                             is pref slip #2

If PreeferMadnessTNG were a real application, it would use either
PreeferSinglePrefFloater.t OR PreeferMultiplePrefsOverview.t, NOT both
(thats XOR for those real hackers out there). But since it is a sample
that demonstrates it all...

The other protos not listed above are:
  PreeferFormulaItem   - added to the system Formulas application
  PreeferAutoPrefsItem - added to the system Preferences application
  protoPrefsOverview   - proto that PreeferMultiplePrefsOverview.t uses

protoPrefsOverview is provided for you enjoyment and use. All you need to
do is set the prefItemsArray and all will work. Just consider the
guts "magic" (unless you really are a hacker).
