User Interactions in Apple Event-Driven Applications
So far throughout the history of the Macintosh, most applications have been designed to be run by a user double-clicking the icon of an application (or document) in the Finder and manipulating the application and its data through the graphical interface. Recently, the publishing industry has adopted AppleScript and scriptable applications as the mechanism for creating production systems. Now that scripting and Apple events have become more pervasive, and more and more applications are scriptable, applications must be prepared to be controlled remotely by Apple events from other applications and scripts. And there's a new kind of application on the horizon, the Apple event-based server application. A server application has no user interface: it's designed to communicate with the outside world only through Apple events. Although server applications have been possible to write since the introduction of System 7, they're becoming increasingly important and will play a major role in the future versions of the Mac OS.
In other words, there may not be a human being sitting at the computer where your application is running.
In this column, I'll cover these topics:
An example scenario. Let's look at a common case that may or may not require user interaction: handling the Core suite's Close event. According to the Apple Event Registry, one of the optional parameters for this event is the saving parameter, which can have one of three enumerated values: yes, no, and ask. The traditional meanings of these values are as follows:
So what should you do? The solution is to call the routine AEInteractWithUser, and then decide what to do based on its return result. But before getting into that, we'll take a look at how the Apple Event Manager decides whether user interaction is appropriate.
The user interaction level. The Apple Event Manager first checks the user interaction level of your application. You can call AEGetInteractionAllowed yourself to determine which Apple event sources can cause your application to interact with the user. If you need to change the interaction level, you can set it at any time with AESetInteractionAllowed.
The Apple Event Manager provides a data type, AEInteractAllowed, which is an enumeration that defines three levels of allowable interaction:
There's a fourth possibility for some applications, the true lowest level of interaction, which is "no interaction." This is the appropriate level in a background-only application or any pure server application, or any other situation where interaction is undesirable. Consider this example (which Jon Pugh came across when he was working for Storm Technologies, while implementing scriptability in PhotoFlash): An attached script is executed as part of an automation process. The script gets an error and the application puts up a dialog box -- but there's no one there to answer it. If users can execute a script inside your application and the script might be run without a user present, you'll have this problem. Before running the script, the user needs to be able to tell your application, "No one will be here, so don't interact."
Since the Apple Event Manager doesn't provide support for the no-interaction condition (the AEInteractAllowed type has only three possible values), you'll have to set up and maintain this yourself. The simplest way to implement this setting is by using a global Boolean variable for the no-interaction flag. If the variable's value is true and your application is called on to do interaction, you'll know right away not to allow the interaction. (Note that if your application handles multiple concurrent Apple events using threading, an application global is not a good solution.)
Because AppleScript doesn't provide a way to get or set interaction levels from scripts, you'll need to implement a user interaction level property for your application, similar to the one in PhotoFlash, that a user can set or get from a script. This property should handle all four enumeration constants and associate the fourth level, no interaction, with the global Boolean variable. In your 'aete' resource, use the following terminology and 4-byte codes for the enumeration constants:
The event source attribute. The next step taken by the Apple Event Manager is to examine the event source attribute of the particular Apple event being handled. If you want to look at the source for an Apple event, you can call AEGetParamPtr with the keyEventSourceAttr keyword to obtain the source. The source data type, AEEventSource, is an enumeration indicating five possible sources: unknown, direct call, same process, local process, and remote process. This is checked against the user interaction level to find out whether your application allows user interaction in response to an Apple event from this particular source.
The interaction-requested attribute. Finally, if the Apple Event Manager determines that interaction with the user in response to the event source is OK, it examines the event's interaction-requested attribute, which tells the Apple Event Manager what kinds of interaction are requested by the Apple event. If you want to look at this level yourself, you can call AEGetParamPtr with the keyInteractLevelAttr keyword to obtain the interaction level requested by the Apple event. There are three constants that represent the interaction levels:
When present, an additional constant that's set by the sender of the event, kAECanSwitchLayer, contributes to determining whether you may bring yourself to the foreground if you need to interact.
If the interaction-requested attribute is present, both its value and the user interaction level (obtained from AEGetInteractionAllowed) determine whether you can interact. Otherwise, the default rules apply: if the event is remote, the default is "never interact"; otherwise the default is "can interact." This default scheme has the advantage that the interaction levels work out neatly for events sent to your application from yourself -- that is, from attached or embedded scripts running inside your application or from your factored user interface -- since the default for events on the same machine is "can interact." (Note that the "never interact" value for the interaction-requested attribute is different from the "no interaction" user interaction level described earlier. The former is an event attribute set by the sender of the event, while the latter is a setting in the server application.)
In the old days, shortly after System 7 was released, developers used to call the GetCurrentProcess routine, followed by SetFrontProcess to switch layers. In that case, an application won't actually go to the foreground until the next call to WaitNextEvent, which usually won't happen until the application returns to the main event loop. Moreover, you can't later prevent your application from coming to the foreground if you're able to correct a problem and no longer need to be in the foreground. Since we're talking here about the situation where you're in an Apple event handler when this happens, don't call SetFrontProcess to make yourself the active application; there's no need to do this. Developers have also used the Notification Manager to put up an alert, beep, place a diamond mark in the Application menu, call Mom in Florida, and so on. This is somewhat better, but still more difficult than it has to be.
It turns out that finding out whether you should interact with the user and getting yourself into the foreground are really easy with the Apple Event Manager. What? "Apple Event Manager" and "easy" in the same sentence? Yes, it's true! The correct, easy, and fun way to do this is by calling AEInteractWithUser (which will call the Notification Manager on your behalf to get the user's attention):
err := AEInteractWithUser(timeOutInTicks, notificationRec, idleProc);What's more, this works even in situations where there's no Apple event being handled (whenever you need to gratuitously get yourself into the foreground, right where you are in your code).
If AEInteractWithUser returns noErr, you're in the foreground and it's safe to interact. That's it! The conditions discussed earlier are automatically tested for you, so you won't have to do any of that yourself.
Be sure to check the error that AEInteractWithUser returns. If it's not appropriate for you to interact, AEInteractWithUser returns errAENoUserInteraction. Also, be aware that AEInteractWithUser can time out if timeOutInTicks is reached before the user responds to the notification. You should supply a reasonable timeout value for timeOutInTicks, and if AEInteractWithUser times out, return errAETimeout or some other suitable error as the result for your event handler. And remember that the original Apple event can time out if the notification is outstanding for too long.
Listing 1 shows a very simple routine that calls AEInteractWithUser, checking the no-interaction flag if requested. You should call this routine before every alert or dialog box that you may present, and handle the situation another way if you aren't allowed to interact.
Listing 1. Interacting with a user while handling an Apple event
FUNCTION AllowInteraction(timeOutInTicks: LongInt;
checkNoInteractFlag: Boolean): Boolean;
VAR
procSerNum: ProcessSerialNumber;
BEGIN
(* If the no-interaction flag should be checked and that flag
is true, don't allow any interaction. *)
IF checkNoInteractFlag & gNoInteract THEN
AllowInteraction := false
ELSE
BEGIN
(* After executing the next line, your application should
be in the foreground, unless it times out, or unless
interaction isn't appropriate. Note that gIdleProc is
usually your Apple event idle proc. *)
err := AEInteractWithUser(timeOutInTicks, gNotificationRec,
gIdleProc);
IF err <> noErr THEN
... (* errAETimeout, or some other error *)
AllowInteraction := err = noErr;
END;
END;
So, in our earlier Close event example, the saving yes and saving ask cases work out a little differently than you might have expected: if AEInteractWithUser returns noErr, put up the alert or dialog; if not, return from the Close event handler with errAENoUserInteraction, errAETimeout, or some other suitable error.
If you end up presenting an alert or dialog box in response to an Apple event for which you shouldn't interact (because for some reason you weren't sure whether you should interact or not), it's best to time yourself out by dismissing the dialog after a reasonable time, even when no one has clicked any of its buttons. You might consider doing this even if interaction is allowed; after a lengthy time, put your application out of its misery and move on. Just be careful which button you choose -- you might want the effect of canceling out the dialog, or producing the least damage, or losing the least amount of work. If you choose to continue processing, be prepared to use suitable defaults, if applicable.
An example of an Apple event scenario that always involves interaction with the user is handling the Edit Graphic Object (EGO) event. EGO is an Apple event specification devised by Allan Bonadio in 1991. In the EGO scenario, an application that contains an embedded object that was created by another application allows a user to edit the object in the creating application. If you do need to pull yourself to the front immediately (such as with EGO), bypassing any possibility of Notification requests, you should call SetFrontProcess followed by AEInteractWithUser. You can insert the following just before the call to AEInteractWithUser in Listing 1 (in C, the parameter procSerNum in the GetCurrentProcess call needs to be a pointer):
err := GetCurrentProcess(procSerNum); err := SetFrontProcess(procSerNum);Because the Apple event always results from a user action, in this situation it's OK to force yourself into the foreground -- this may be the only reasonably significant case where you should do this.
And, as in the case of AEInteractWithUser, you should be careful about pending update events while your alert or dialog box is on the screen.
When your application is more likely to be controlled by a batch process, such as a script that runs periodically in a production system, avoid requesting user interaction when the computer is likely to be unattended. (When you're not sure how you're being controlled, performing the tests discussed earlier in "Behind the Scenes" may help you find out.) You don't want an alert popping up on a screen when there's no one to respond -- this can cause the computer to come to its knees and, depending on what other applications are running, may even cause it to stop processing anything else.
Dealing with the problem yourself. Not being able to interact when you want to is a problem that can arise from any of the following: you're faced with the error errAENoUserInteraction (or your AllowInteraction function returns false); AEInteractWithUser times out; or you implement "no interaction" as a user interaction level. In some cases, the best thing to do is to try to handle the situation yourself.
If the situation doesn't require the user to make a choice or supply any information -- that is, if you just want to tell the user something -- don't hold up the works for this; simply skip the interaction. But if you do require a choice or some information, consider handling this situation intelligently in the application. Users will have a better experience if they come back from lunch (or the next day) to find that your application carried on instead of stopping after the first 20 seconds because it needed some small piece of information. For example, if an Apple event is missing a required parameter, and the inability to put up a dialog box means that you can't request information from the user, see whether you can use default values instead.
Be careful what behavior you choose when the user isn't available to decide. And don't go overboard by trying to second-guess a user -- that can cause genuine irritation. If you really, really need to interact but you can't, it's acceptable to generate an error such as errAENoUserInteraction. Judge what's best for your application, based on who uses it and how it's used.
Returning an error to the Apple event. Sometimes the best way to avoid user interaction is to return an error describing what went wrong through your Apple event reply. For server applications, this is the only way to interact. It puts the burden of responsibility in the hands of the Apple event's sender, which is often a script or another application running on another machine. This way, you're off the hook -- the decision about whether to find and disturb a user is made by another process. As shown in Table 1, the Apple event error-reporting mechanism provides several error parameters that you can use to more concisely describe the nature of the problem.
Table 1. Apple event error parameters
Parameter
Note: The AppleScript keywords are those used in the error and on error commands.
It's important to come up with unique error numbers, because the text for the corresponding error messages should be localized and thus may vary from location to location and system to system. The numbers are the best means for the sending application or script to trap errors, since they won't vary.
Normally the error code you return from your Apple event handler becomes the error number, so there's no need to explicitly supply an error number parameter. It's better to use the error number as the return value from your event handler, rather than stuffing it as a parameter in the reply event yourself, because the error code will become the return value for the call to AESend in the sending application or script, which can immediately detect that something went wrong with the handling of the Apple event. (However, if you suspend an Apple event, you must place the error number explicitly in the error number parameter of the reply before resuming the event.) In any case, all other error parameters must be placed in the reply event with AEPutParamPtr or AEPutParamDesc. As an example of setting an error parameter, here's how to provide an error string to an Apple event reply:
err := AEPutParamPtr(reply, keyErrorString, typeChar, @messageStr[1], length(messageStr));If you want to cancel an operation, you'll typically return error -128 (userCanceledErr), which is the most reliable way to stop executing a script that's sending an Apple event to your application. The exception to this rule occurs when the Apple event was sent from a script command that's inside a try block that specifically traps for that error; in this case, you may not be able to halt the script.
Note that there are many cases where either you can't return errors or, if you can, they'll be ignored. An Apple event sent with a send mode of kAENoReply doesn't have a reply event. So if you try to stuff parameters such as error parameters into this nil reply, you'll die horribly. You can also get a nil reply event if the Apple event is sent by an AppleScript command in an ignoring application responses block. Furthermore, the Finder ignores errors returned to Apple events it sends, such as the Required suite's Open Documents event that's sent when icons are dragged onto your application's icon. And a user can trip you up by enclosing an AppleScript command in a try block (try...on error...end try); you'll still get a reply event, but the script that executes the command can ignore any error information you return in the reply, or ignore your error altogether. There's no specific strategy to follow in these cases, since you can't know when this is happening, but be aware that it can happen.
Supplying a missing data value. Part of the design of your error-handling scheme includes determining that it isn't always necessary to return an error. Rather than cause an error, sometimes it's better to return noErr and place a Boolean indicator value or an empty list in the direct parameter as the result. This depends mostly on which Apple event you're handling.
For example, if you receive a request to find or use an object or a file that doesn't exist, you should return an appropriate error, such as errAENoSuchObject or fnfErr. (The exception to this is the Does Object Exist event, where you always want to return a true or false value.) On the other hand, if the request is to search for all items matching a certain criterion, you may want to return an empty list if nothing matches the criterion. This way the sending application or script won't fail, and the script can just check the result instead of having to trap for errors.
The techniques I've described in this column apply whether Apple events are an alternative to the graphical interface or your application is designed specifically as an Apple event server application. If your application will be controlled through Apple events, decide when it's appropriate (and when it's not appropriate) to interact with the user, by performing the tests discussed in this column. A well-planned interaction and error code-and-message scheme can make it possible for users to run your application in situations where a user isn't in control.
CAL SIMONE (mainevent@his.com) eats, drinks, and sleeps AppleScript. Just when he thought he was out of the woods, the AppleScript Language Association (ASLA) was born. Oh well, maybe next year he'll get to take that vacation. And why didn't Cal write a column for the last couple of issues of develop? Let's see...his company shipped a product, and he participated in six trade shows, moved to a new apartment, and solved the world hunger problem (just kidding about that last one).*
Thanks to Andy Bachorski, Sue Dumont, and Jon Pugh for reviewing this
column.*
For recently updated vocabulary advice from Cal, see this issue's CD or develop's Web site, under Additional Articles.*
