---

Suspending and Resuming Apple Events and Script Commands

Starting with Mac OS X version 10.3, the NSAppleEventManager class provides methods for suspending and resuming an individual Apple event. These methods are of use for applications that respond to Apple events without using the built-in Cocoa scripting support. For applications that do take advantage of the Cocoa scripting support, NSScriptCommand provides methods for suspending and resuming execution of a script command.

An application typically suspends an Apple event (or a script command) when it performs an asynchronous operation, so that the application won’t receive any more Apple events from the same script until it completes handling of the current event (or script command). For example, suppose the application must display a sheet as part of obtaining information to return in a reply Apple event. If so, it can suspend Apple events (or a script command) before displaying the sheet, insert information into the reply Apple event after the user dismisses the sheet, then resume. This need to suspend and resume can occur with other asynchronous operations (including those that may be open-ended or take a long time to complete).

To suspend an Apple event, you use the NSAppleEventManager method suspendCurrentAppleEvent, which returns a suspension ID (NSAppleEventManagerSuspensionID) for an Apple event being handled on the current thread. You can pass this suspension ID to appleEventForSuspensionID: to get an Apple event descriptor for the suspended event, or to replyAppleEventForSuspensionID: to get a descriptor for the corresponding reply Apple event. To resume a suspended Apple event, you pass the associated suspension ID to resumeWithSuspensionID:. In Mac OS X version 10.4, this method can be invoked in any thread.

To suspend a script command, use the NSScriptCommand method suspendExecution. This method suspends execution of a script command if the receiver is being executed in the current thread by the built-in Cocoa scripting support (that is, the receiver would be returned by [NSScriptCommand currentCommand]). You use resumeExecutionWithResult: to resume a suspended script command. In Mac OS X version 10.4, this method can be invoked in any thread.

---