Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support

Apple IIgs
#53:    Desk Accessories and Tools

Revised by:    Dave Lyons    September 1990
Written by:    Matt Deatherage & Jim Mensch    March 1989

This Technical Note discusses compatibility issues that can arise between desk 
accessories and applications.  Where possible, it presents solutions.
Changes since November 1989:  Added to the discussions of Close with reference 
number zero and of when applications should start and shut down tools.  Noted 
that StartUpTools is not intended to be called from an NDA.
_____________________________________________________________________________

Desk accessories vary widely in complexity.  Classic Desk Accessories (CDAs) 
range from simple status-reporting programs to complete system-level debugging 
utilities, and similarly, New Desk Accessories (NDAs) range from static 
windows with pictures to nearly full-fledged applications.

This Note presents some new guidelines aimed at helping developers of both 
applications and desk accessories to get their products to work together now 
and in the future.


Tool Sets

The greatest conflict between applications and desk accessories, especially 
NDAs, is the use of system tool sets.  The Apple IIgs Toolbox Reference, 
Volume 1, defines which tools are available for use by NDAs.  The Desk Manager 
requires starting the following tool sets before calling FixAppleMenu (which 
installs the names of the NDAs in the Apple menu):

    Tool Locator (#1)
    Memory Manager (#2)
    Miscellaneous Tools (#3)
    QuickDraw II (#4)
    Event Manager (#6)
    Window Manager (#14)
    Menu Manager (#15)
    Control Manager (#16)
    LineEdit (#20)
    Dialog Manager (#21)
    Scrap Manager (#22)


Since the Desk Manager requires starting these tools before calling 
FixAppleMenu, NDAs may assume that these tools are all present and running, so 
they do not need to check for their presence.  In addition to these 
requirements by the Desk Manager, Apple strongly recommends that all 
applications start the following tools:

    QuickDraw Auxiliary (#18)
    Font Manager (#27)

These two additional tools are so widely used by desk accessories that they 
should be present.  NDAs may not assume their presence, but it is reasonable 
to write an NDA that checks for them, with the assumption that they usually 
turn out to be available.


The Golden NDA Guideline

Developers who wish to maintain maximum compatibility between their NDAs and 
applications, both now and in the future, should consider every environment 
change they make with the following Golden NDA Guideline firmly in mind:

    "I, an NDA, pledge not to alter the environment of the application 
    under which I run, and I will behave in such a way that the 
    application runs the same whether I am present or not."

Of course, this guideline does not include such necessary tasks as the normal 
(and reasonable) allocation of memory.  An application must be prepared to 
handle a memory allocation call by a desk accessory, operating system, or even 
a tool at unexpected times.  The guideline does, however, mean that your desk 
accessory cannot change the operating environment, including such things as 
the presence of tools and operating system parameters.  The following sections 
detail some of the most important ways to follow the Golden NDA Guideline.


Desk Accessory Guidelines

Extra Tools

  o  If an NDA needs to use a tool which is not guaranteed to be available 
     (e.g., Standard File), it should check to see if the tool is already 
     running.  If it is not running, the NDA must use LoadOneTool to load it, 
     then it must start the tool before using it.  When finished with the 
     tool, the NDA must shut it down and unload it with UnloadOneTool.  (A 
     tool is already running if its xxxStatus function returns TRUE and no 
     error.)

  o  If an NDA needs to start up a tool and keep it started while letting the 
     application continue to run, things quickly get complicated.  If your 
     NDA starts a tool which the application is going to use but has not yet 
     started (i.e., the Font Manager), and your NDA does not shut it down 
     before the application regains control, the application (in this 
     example) gets error $1B01 (Font Manager Already Started) when it makes 
     an FMStartUp call.  Many applications stop gracelessly on getting a tool 
     startup error.

     A previous version of this Note advised NDAs to start up and shut down 
     tools when their windows were activated and deactivated.  This approach 
     isn't strong enough to solve all the problems, since the application may 
     decide to start up tools based on menu items (which can still be 
     selected while an NDA window is in front).

     The only completely safe way to use a tool that isn't already running is 
     to start it, use it, and shut it back down without ever returning 
     control to the application while the tool set is started.

     Starting QuickDraw Auxiliary when the application has not started it can 
     get you into a lot of trouble:  an application that correctly implements 
     320/640 mode switching calls QDShutDown and QDStartUp.  QuickDraw 
     Auxiliary depends heavily on QuickDraw, and restarting QuickDraw while 
     QuickDraw Auxiliary is active easily toasts you.

  o  StartUpTools is designed to be called only by an application, not a desk 
     accessory.  Unexpected things happen if your NDA calls StartUpTools (for 
     example, you may get a second copy of the application's resource fork 
     open in your NDA's private resource search path; this wastes RAM and can 
     interfere with an application's attempt to write to its own resource 
     fork).  For now, do not call StartUpTools from a DA.

  o  If your NDA allocates bank-zero work area space for tool sets, be sure 
     to dispose of it at DeskShutDown time (when your DAInit entry is called 
     for shutdown).  If you don't, the system dies with error $0201 when 
     trying to launch a ProDOS 8 application, since GS/OS needs all of banks 
     0 and 1 to start ProDOS 8.

  o  Sound tools are an exception to the rule of freely using a tool which is 
     already started.  Refer to the section on System Parameters for more 
     details on using sound tools.

  o  NDAs must not shut down tools which they have not started.

  o  CDAs are nearly always modal, but by using the HeartBeat interrupt queue 
     or other mechanisms, they can get control when the user is no longer 
     "in" the CDA.  The list of guaranteed tools for NDAs does not apply to 
     CDAs, and CDAs must be prepared to deal with the ProDOS 8 environment as 
     well as GS/OS.

System Parameters

  o  A desk accessory (CDA or NDA) must not change a system resource or 
     parameter which cannot be restored to its original condition.  A 
     trivial, but illustrative, example of this is the number of times a 
     pull-down menu item blinks when you select it.  This number (three by 
     default) may be changed with the SetMItemBlink call, but there is no 
     corresponding GetMItemBlink call, so you cannot retrieve the current 
     value.  Therefore, a desk accessory must not change this parameter, and 
     the same rule applies to any other system parameter for which you cannot 
     determine a current value.

  o  This idea extends to calling tool startup functions.  Even though a 
     tool's startup function may not return an error when the tool is already 
     active, the startup function could reset certain parameters upon which 
     the application depends.  An example of this is TLStartUp for the Tool 
     Locator.  A seemingly innocuous call, TLStartUp actually disconnects any 
     user tool sets present, which, in this case, would most likely have been 
     installed by the current application.  CDAs and NDAs must never call 
     TLStartUp or TLShutDown.

     A desk accessory should generally not call a tool's startup function if 
     the tool is already active.   Two exceptions are (1) the Memory 
     Manager's MMStartUp call, which you can think of as a "GetMyID" call, 
     and (2) ResourceStartUp, because the Resource Manager needs to be 
     started up explicitly by each client (see Apple IIgs Technical Note #71, 
     Desk Accessory Tips and Techniques).

  o  A desk accessory cannot use any of the sound tools if they are already 
     started.  This is contrary to the rule for other tool sets, but it is 
     required because there is no memory management of the sound RAM (or "DOC 
     RAM").  If the Sound Tools (#8) are started, the application has 
     exclusive control of the 64K DOC RAM used to play sounds.  Anything your 
     desk accessory might put there could overwrite information the 
     application needs.

     Saving and restoring DOC RAM around desk accessory usage is not 
     sufficient.  Many of the sound functions are interrupt driven, altering 
     the contents of DOC RAM only during sound interrupts, so your desk 
     accessory might attempt to replace parts of DOC RAM which are being 
     played.  Since there is no memory management of DOC RAM, desk 
     accessories must avoid the sound functions of the IIgs if the 
     application is already using them.

  o  A desk accessory must not install user tool sets, because there is no 
     arbitration of user tool set numbers.  User tool sets are the sole 
     property of the current application.

     A desk accessory should not call user tool sets even if it determines 
     that the host application has installed a certain tool set, because that 
     limits future system software options.  For example, consider a 
     hypothetical multiple-application environment.  If DAs call user tool 
     sets and the system automatically switches between separate collections 
     of user tool sets, there would be no way for the system to know which 
     set to switch in before giving control to a desk accessory.


Application Guidelines

To coexist peacefully with desk accessories, particularly NDAs, applications 
need to follow the guidelines listed in the Desk Manager chapter of the Apple 
IIgs Toolbox Reference, Volume 1.  However, those applications which wish to 
ensure maximum compatibility now and in the future also want to adhere to the 
following:

  o  Be careful about when your application starts and shuts down tools.  A 
     highly compatible approach is to start tools at the beginning of your 
     application and leave them started.  For certain tools, like Standard 
     File, it is reasonable to load and start the tool set each time it's 
     needed (you may want to check whether it's already started, in case some 
     impolite NDA started Standard File and left it started).

     Note that UnloadOneTool followed later by LoadOneTool does not 
     necessarily cause disk access or ask the user to insert the boot disk.  
     UnloadOneTool calls UserShutDown to put the tool set into "zombie" 
     state, where it can be restarted from memory if none of its segments 
     have been purged.  Unloading tools while they aren't in use is a Good 
     Thing--if the user has plenty of RAM, there's no noticeable performance 
     hit, but if RAM space is tight then doing extra disk access is 
     preferable to actually running out of memory.

     For maximum compatibility, an application should not shut down any tools 
     which were ever active when you called SystemTask or TaskMaster (until 
     quitting time, of course, when you shut down everything, starting with 
     the Desk Manager).  You can start more tools, but do not shut down those 
     which are already active.  If you intend to start a tool and not keep it 
     started, use it and then shut it down immediately, being sure not to 
     call SystemTask or TaskMaster during that time.

     Future system software may provide arbitration of tool set use, but for 
     now these guidelines provide a solution with which you can work.

  o  Don't just start the Scrap Manager--use it!  Many desk accessories 
     support cutting and pasting to exchange text and pictures with your 
     application, but they can do it only if you use the Scrap Manager.  If 
     you have a need for your own private scrap internally, you should still 
     also use the Scrap Manager to exchange text and pictures with other 
     applications and DAs.

  o  Applications should not call CloseAllNDAs while shutting down.  Since 
     DeskShutDown closes all open NDAs anyway, it's not necessary.  By not 
     calling CloseAllNDAs, you allow the system or NDAs to tell the 
     difference between just cleaning up and really wanting to close all the 
     NDAs.

  o  Applications should never make a Close call with reference number zero 
     at file level zero.  (If you need to use Close with reference number 
     zero, use GetLevel and SetLevel to avoid closing files you did not open.  
     Desk accessories should open files at level zero to ensure their files 
     stay open when a DA-friendly application is using this scheme.)  It 
     would be good if the system provided Desk Accessories with a way to open 
     files and be certain that an application can never close them by 
     accident, but for now this is a solution with which you can work.

  o  An application with some memory to spare can save NDAs time by providing 
     them the additional tools which they are most likely to use.  If a desk 
     accessory needs the List Manager and your application starts it, the 
     desk accessory runs faster since it can avoid loading and starting the 
     tool every time it gets control.

     The most common tools which desk accessories require besides those 
     available in the standard Desk Manager set are QuickDraw Auxiliary 
     (#18), the Print Manager (#19), Standard File (#23), the Font Manager 
     (#27), and the List Manager (#28).  QuickDraw Auxiliary and the Font 
     Manager are especially important--not only do they work well together, 
     but they are also widely used.  In addition, FMStartUp can take a long 
     time, and waiting for it every time you activate an NDA window can be 
     really frustrating.  Many desk accessories also use the Print Manager, 
     the List Manager, and Standard File, and if they are always available, 
     desk accessories work more smoothly with your application.


Further Reference:
_____________________________________________________________________________
  o  Apple IIgs Toolbox Reference
  o  Programmer's Introduction to the Apple IIgs
  o  Apple IIgs Technical Note #71, Desk Accessory Tips and Techniques

