home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / Newton Platform Info / Newton 2.0 Sample Code / User Interface / PreeferMadnessTNG-1 / PreeferMadnessTNG.README < prev    next >
Encoding:
Text File  |  1996-02-19  |  5.2 KB  |  116 lines  |  [TEXT/R*ch]
  1. /*
  2. **      Newton Developer Technical Support Sample Code
  3. **
  4. **      PreeferMadnessTNG, How to do preferences for your application
  5. **
  6. **      by Maurice Sharp and David Fedor, Newton Developer Technical Support
  7. **
  8. **      Copyright © 1996 by Apple Computer, Inc.  All rights reserved.
  9. **
  10. **      You may incorporate this sample code into your applications without
  11. **      restriction.  This sample code has been provided "AS IS" and the
  12. **      responsibility for its operation is 100% yours.  You are not
  13. **      permitted to modify and redistribute the source as "DTS Sample Code."
  14. **      If you are going to re-distribute the source, we require that you
  15. **      make it clear in the source that the code was descended from
  16. **      Apple-provided sample code, but that you've made changes.
  17. */
  18.  
  19. Once upon a time there was a sample called PreeferMadness. This sample showed
  20. you everything you need to do for preferences and formulas. It even provided
  21. you with protos for pref items. Then Newton 2.0 OS came along.
  22.  
  23. So here is PreeferMadnessTNG (The Next Generation). Like its elder, it shows
  24. you all you need to know for preferences and formulas. But now it does it the
  25. Newton 2.0 OS way.
  26.  
  27.  
  28. Application Preferences
  29. -----------------------
  30. Preferences for your application are accessed through the "Prefs" item in a
  31. protoInfoButton. The code that implements this is in PreeferMadness.t. The
  32. info button is in the menuLeftButtons array of the newtStatusBar. The
  33. method to open the prefs slip is in MyBase.DoInfoPrefs.
  34.  
  35. Once the user taps on the Prefs item, what you bring up depends on how
  36. many preferences your application has.
  37.  
  38. If all of your prefs can be logically grouped into one slip, then you
  39. should bring up your prefs inside a protoFloatNGo. The slip must have a
  40. title (protoTitle) that is "<app-name> Preferences". It should be centered
  41. in your application base view. For an example see the Names application
  42. preferences.  This is demonstrated here in PreeferSinglePrefFloater.t.
  43.  
  44. If you need more than one logical grouping, bring up a floating overview of
  45. your preference choices. This sample provides you with a user proto
  46. template called protoPrefsOverview that you can use as the basis of your
  47. preferences overview. This is similar to the Prefs application in Extras,
  48. and is demonstrated in PreeferMultiplePrefsOverview.t.
  49.  
  50. If you use protoPrefsOverview, each preference panel (i.e., grouping of
  51. logically related preferences) must use a protoPrefsRollItem as the base
  52. view. See PreeferAppPrefsItems or PreeferPhilPrefItem for examples.
  53.  
  54. If you have a single preference, this sample expects the panel to be based
  55. on protoPrefsRollItem. If you do not want to use that proto, you will be
  56. responsible for providing the correct UI.
  57.  
  58. Remember that you can use GetAppPrefs to get your application preferences
  59. frame. The frame returned by that call is a soup entry, so you can use
  60. EntryChange to update changes to your preferences.
  61.  
  62.  
  63. System Preferences
  64. ------------------
  65. PreeferMadnessTNG also shows you how to add something to the system
  66. preferences. Note that nearly no applications need to do this. The only
  67. reason to do this is if you are an auto part that requires preferences and
  68. can not set them through some system provided mechanism (e.g., transports
  69. use the I/O box Prefs item).
  70.  
  71. Adding the preference is easy. See the InstallScript and RemoveScript
  72. inside PackageStuff.t. The preference panel itself (PreeferAutoPrefsItem)
  73. is also based on protoPrefsRollItem.
  74.  
  75. Note that unlike an application preference, your system preference must
  76. have an appropriate icon. See the icon slot in the base view of
  77. PreeferAutoPrefsItem. Notice that this icon is smaller than those used for
  78. your application. It should be no larger than 14 x 12. At that size it may
  79. look a little wierd. Experiment, have fun, but make it meaningful.
  80.  
  81.  
  82. Formulas
  83. --------
  84. Adding a formula is straightforward. See the InstallScript and RemoveScript
  85. inside PackageStuff.t. PreeferMadnessTNG provides the PreeferFormulaItem
  86. user proto that you can easily adapt for your own formula items.
  87.  
  88.  
  89. Roadmap
  90. -------
  91. Here's a partial "roadmap" showing what view contains (or opens) what other
  92. view(s), since there are a bunch of files in this sample.
  93.  
  94.   PreeferMadness.t                                application base view
  95.  
  96.     PreeferSinglePrefFloater.t                   contains one pref slip
  97.         PreeferAppPrefsItems                       is the app pref slip
  98.  
  99.     PreeferMultiplePrefsOverview.t           overview of multiple slips
  100.         PreeferAppPrefsItems                            is pref slip #1
  101.         PreeferPhilPrefItem                             is pref slip #2
  102.  
  103. If PreeferMadnessTNG were a real application, it would use either
  104. PreeferSinglePrefFloater.t OR PreeferMultiplePrefsOverview.t, NOT both
  105. (thats XOR for those real hackers out there). But since it is a sample
  106. that demonstrates it all...
  107.  
  108. The other protos not listed above are:
  109.   PreeferFormulaItem   - added to the system Formulas application
  110.   PreeferAutoPrefsItem - added to the system Preferences application
  111.   protoPrefsOverview   - proto that PreeferMultiplePrefsOverview.t uses
  112.  
  113. protoPrefsOverview is provided for you enjoyment and use. All you need to
  114. do is set the prefItemsArray and all will work. Just consider the
  115. guts "magic" (unless you really are a hacker).
  116.