WRITING PROGRAMS FOR MULTIFINDER

Chris Derossi

MultiFinder, Apple's multitasking extensions to the Mac OS, was first introduced with System 4.2 and was later enhanced with System 6.0. Although the use of MultiFinder is now familiar to most, programmers writing for the MultiFinder environment still find themselves faced with some confusion. In this article, I'll address some of the issues relating to programming for MultiFinder and hopefully clear up much of the confusion.

Sometimes programming for the Macintosh is like trying to shoot at a moving target. As the Mac system software changes, so do the rules for writing " well-behaved" programs. This is part of the reason why programming the Mac today seems to be extra-complicated.

Prior to System 4.2 (pre-MultiFinder), each application for the Mac effectively owned the entire machine during its execution. There were guidelines then for writing programs that were considered well-behaved and compatible, but they were just that --guidelines. In the interest of getting just a little bit more functionality or a little bit more performance, these rules were sometimes bent or simply ignored.

Enter MultiFinder. Not only did MultiFinder tend to break programs that broke the rules, but also the rules themselves changed. Programs had to learn to run in a world in which everything -- such as the file system, memory, events, and the screen --was shared.

At the same time as programs were being revised to become MultiFinder compatible, a new class of programs was born. These MultiFinder-aware applications were designed to take advantage of a multitasking environment. Such programs could do background processing and deal intelligently with being suspended and resumed.

With System 6.0 some new features were added to MultiFinder. Applications being written or revised today have a different set of guidelines to follow than did programs written for MultiFinder and System 4.2. Such is the price we pay to have software that evolves with the times. Of course, the changes between System 4.2 and System 6.0 are less dramatic than the changes that went along with MultiFinder' s introduction.

One of the things that has changed is the SIZE resource. It was originally defined so that Switcher could know something about applications, such as the amount of memory they need. MultiFinder adopted the SIZE resource, ignoring the Switcher flags and defining new flags. Each flag in the SIZE resource tells MultiFinder something about how the application wants to be executed or how much the application understands.

The bits in the flags field have been cause for some confusion for several reasons. First, it isn't always clear exactly what each flag means or what the results are of setting each one. Also, even though each bit can be set independently of the others, there is a relationship between some of the flags that may not be obvious. Finally, some of these flags have had different names at different times.

Here is a description of each flag along with the effects of setting or not setting that flag. These descriptions are in the order that you would most likely want to consider them for your application.

   type 'SIZE'  {

     boolean   dontSaveScreen           /* No longer used */
               saveScreen;

     boolean   ignoreSuspendResumeEvents,
               acceptSuspendResumeEvents;

     boolean   enableoptionSwitch,      /* No longer used */
               disableoptionSwitch;

     boolean   cannotBackground,
               canBackground;

     boolean   notMultiFinderAware,
               multiFinderAware;

     boolean   backgroundAndForeground,
               onlyBackground;

     boolean   dontGetFrontClicks,
               getFrontClicks;

     unsigned bitstring[9] = 0;         /* reserved    */
          /* Memory sizes are in bytes */
     unsigned longint;                  /* preferred mem size */
     unsigned longint;                  /* minimum mem size */
   };

getFrontClicks -- If the user brings your application to the front by clicking on one of its windows, the mousedown event is normally used to resume your application only. If this bit is set, though, your application will get the mouse-down (and corresponding mouse-up) event that brought you to the foreground. This can be used to provide better responsiveness to the user.

For example, the Finder accepts these mouse-down events so you can click on an icon when the Finder is in the background. The Finder will come to the foreground and select the icon immediately, without your having to click on the icon a second time.

This type of action is not appropriate for all kinds of applications, however. If a paint program had this bit set for example, just the act of bringing the application to the front might result in a dot being painted onto the document. The key here is to do what the user expects so that the user never realizes there are two alternatives.

onlyBackground -- If this bit and the canBackground bit are both set, your application will be launched directly into the background. It cannot come to the foreground because it can't have any windows, its name will not show up in the Apple menu, and its icon will not be available in the menu bar.

Most applications will not have this bit set. Only if you are writing an unusual program should you have to deal with this flag. An example of the kind of application that uses this feature is Backgrounder. Backgrounder is launched by MultiFinder and stays in the background. Its sole job is to look for the existence of a spool file and launch PrintMonitor.

In addition to tricking your application into converting its scrap and activating/ deactivating its front window, there are two other times when MultiFinder will fool your application into doing something. One of these happens when the user chooses Restart or Shutdown from the Finder's Special menu. MultiFinder goes through all the currently executing applications and makes them think that the user has chosen Quit. This causes each application to terminate, asking the user to save documents as appropriate for each application.

The other instance of MultiFinder tricking the application happens when an application is already running and the user launches a document for that application from the Finder. MultiFinder switches to that application and posts a mouse-down in the menu bar, selecting the O.n... item from the File menu. Then, when the application calls SFGetFile in response to the Open..., MultiFinder simply returns a reply for the launched document.

This could fail for a couple of reasons. If your application doesn't call SFGetFile or SFPGetFile in response to the Open..., the user will get your application but the document won't have opened. If for some reason a document cannot be opened, your application should gray the Open... item (for example, you support only one document at a time and one is already open).

A far more common reason why MultiFinder's quit or open tricks would fail is nonstandard Quit or Open ... menu items. MultiFinder looks for a menu with the title "File" and items named Quit for quitting and Open (with ellipses), ... (with three periods), ..., or Open Stack for opening documents. If these are not present, the user will have to quit or open documents manually from the application.

If you have nonstandard menus m your application that perform the same action as the standard ones, there is a way to tell MultiFinder what your menu items are called. MultiFinder looks for certain resources in your program that contain the names of your Quit and Open menu items. These resources are of type 'mstr' and are equivalent to the standard 'STR' resource type. Because your Quit and Open items may be in different menus, each of them have a 'mstr' resource for their menu title and a 'mstr' resource for their item name. MultiFinder expects the menu title for the Quit item to be in 'mstr' #100 and the menu item to be in 'mstr' #101. Similarly, the 'mstr' resources for the Open item are #102 and #103.

     File
     New
     Open Document
     _____________
     Save
     Save As...
     Print
     _____________
     Quit MyProgram

     resource 'mstr' (100) ("File");

     resource 'mstr' (101) ("Quit MyProgram");

     resource 'mstr' (102) ("File");

     resource 'mstr' (103) ("Open Document");

resource 'mst#' (101) {
   {
     "File";
     "Files"
   }
 };

resource 'mst#' (102) {
   {
     "Quit MyProgram";
     "Quit to Finder"
   }
 };

Historically, programs that needed to do some work periodically but that didn't have any user interaction would have to be written as drivers that had the dNeedsTime flag set. Examples of this kind of program are daemons, servers, and spoolers. But drivers have to be installed and can't have globals or multiple segments, so writing them could be cumbersome and difficult. MultiFinder now provides a better alternative.

By setting both the canBackground and onlyBackground bits in the SIZE resource, you can write an application that launches directly into the background and never comes to the front. This type of program is ideal for simple, periodic, background tasks. And backgroundonly applications are easier to write than normal applications because they can't have any real user interface. This means that there are no windows, menus, controls, or dialogs to worry about. It also means that the only event that has to be dealt with is the null event; no user events are ever posted to this kind of application.

Plus these programs get all the advantages of being complete applications. Because they run normally and not at interrupt time, they can allocate memory and use handles. They have their own application partition, so they can have globals and multiple segments. And because they're not drivers, they don't have to be installed in the unit table; they can have icons and be launched just like any other application.

A background-only application doesn't have a layer of its own because it doesn't have any windows. Even if it tried to put up a window, dialog, or alert, it wouldn't succeed. But there is a way that such a program can communicate with the user if it needs to. This is one of the responsibilities of the Notification Manager.

The Notification Manager allows a background application to display an alert, make a sound, or put an icon in the menu bar. In this rudimentary way, a backgroundonly application can alert the user to error conditions, changes in the environment, or tasks completed.

If you are writing an application today, or revising an old application, it pays to make it MultiFinder aware. Very little extra code needs to be added, and the benefit of better speed during context switching is well worth it. Similarly, the inclusion of a SIZE resource, and 'mstr' resources if appropriate, will help ensure that MultiFinder works well with your program.

Additionally, many programs will be able to take advantage of processing in the background. Background processing may be the edge your program needs to let your users get the most out of their Macs. Finally, the ability to have background-only applications opens the door for a whole new set of powerful spoolers, servers, and other background tasks.

Programmer's Guide to MultiFinder. APDA product #KMB017. Renton, Wash.: APDA.

MultiFinder Miscellanea. Macintosh Technical Note #180. Renton, Wash.: APDA.

Notification Manager. Macintosh Technical Note #184. Renton, Wash.: APDA.

MultiFinder Revisited. Macintosh Technical Note #205. Renton, Wash.: APDA.