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:
There are some important differences between direct manipulation through the
graphical interface and remote control through interapplication communication. When
developing server applications, you'll want to be careful about what happens when an
Apple event (or series of Apple events) takes over. This applies not only to
applications that are designed to be controlled primarily through Apple events, but
also to those designed to be controlled mainly through a graphical interface but for
which Apple events provide an alternative interface to the graphical one. The
information presented in this column applies to both types of application.
For this discussion, I'll classify Apple-event control into two scenarios:
Since your application may need to respond to either type of Apple-event control, I'll
describe how to comfortably handle both, starting with the way to determine which one
you're dealing with at a particular moment. The largest issue to tackle in responding to
Apple events is whether to interact with the user. I'll explain how to determine
whether you should interact and what to do once you've made that determination.
Incidentally, in a standard factored application (you are factoring your application
these days, aren't you?) you can get most of the proper behavior for free.
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 savingparameter, which
can have one of three enumerated values: yes, no, and ask. The traditional meanings of
these values are as follows:
But it's not quite that simple. For example, assume that the user modifies a document
in one of your application's windows and then runs a script that executes the command
close the front window(with no saving parameter or with saving ask). Your
application's Close event handler will typically display a dialog box asking the user
whether to save the document. The catch is that you can't always do this; it depends on
where the script is running. You could implement a preference setting that allows the
user to configure your application for "response to humans vs. non-humans," but
having too many preferences spoils the simplicity.
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 following conditions are considered by the Apple Event Manager to determine
whether you should interact while handling an Apple event. Note that the first one is an
application setting, while the last two are optional attributes of a particular event that
may be set by the sender.
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:
Remote events will arrive only if all the conditions for accepting remote
events are met. You need to set two flags in the SIZE resource -- "accept
high-level events" (to receive any Apple events) and "allow local and remote
events" (to receive events from other computers) -- and give permission for
program linking in the Users and Groups control panel. You must also make
sure that Program Linking is turned on in the Sharing Setup control panel and
enabled for the application in the Finder's Sharing dialog.*
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:
Apple events initiated from the user interface should probably ignore the
no-interaction flag altogether, and just call AEInteractWithUser and interact in the
usual way if need be. This way your application could perform double duty,
successfully performing actions initiated by Apple events from other sources without
disturbing a user who might be sitting there using the application.
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.)
So how do you make this work in your application? Before initiating user interaction,
you'll need to make sure your application is the active application -- that is, it's in
the foreground. Let's take a moment to discuss the ways to become the active
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.
If your application might have any windows visible when you call
AEInteractWithUser, you must use a filter procedure to handle update,
activate, suspend, and resume events. If you don't do this, you'll lock out other
processes from getting any processor time. For details, including a description
of the hazards of failing to use a filter procedure, see Technote TB 37,
"Pending Update Perils."*
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.
Now that you've determined whether or not to interact in a given situation, let's look at
a couple of things to keep in mind when you put up an alert or dialog box while
handling an Apple event.
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.
What if there isn't a user sitting at the computer? You'll want your application to cope
with limitations or restrictions on user interaction without failing, especially when it
comes to reporting errors properly.
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
keyErrorString or kOSAErrorMessage
keyErrorNumber or KOSAErrorNumber
kOSAErrorPartialResult
kOSAErrorOffendingObject
kOSAErrorExpectedTypetoIn coercions, the type requested in the coercions.
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 atry 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.
When a user is likely to be at the computer while a script controlling your application
is run or while another application is directly communicating with your application,
interacting with the user can be appropriate. Although having the application bring up
alerts and dialogs used to be the norm, it's becoming rarer. Since scripts can interact
with a user, why not let the script do the user interaction when it needs to?
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
ordevelop's Web site, under Additional Articles.*