Introduction to Apple Events Programming Guide

An Apple event is a type of interprocess message that can specify complex operations and data. Apple events allow you to gather all the data necessary to accomplish a high level task into a single package that can be passed across process boundaries, evaluated, and returned with results. The Mac OS uses Apple events to communicate with applications. Apple events are also an essential part of the AppleScript scripting system, which allows users to automate actions using scriptable applications—applications that can respond to a variety of Apple events by performing operations or supplying data.

Note: Mac OS X offers other mechanisms for communicating between processes. These mechanisms are described in “IPC and Notification Mechanisms” in "Darwin and Core Technologies” in Mac OS X Technology Overview.

Apple Events Programming Guide assumes that you are familiar with the information in AppleScript Overview.

The information in this document applies primarily to Carbon applications. While Cocoa applications can take advantage of most of the described features, in many cases they won’t need to. For more information, see “Framework and Language Support.”

Who Should Read This Document

You should read this document if you want to:

Make your Carbon application respond to the Apple events sent by the Mac OS (for launching and quitting applications, opening documents, and so on).
Work with Apple events as part of writing a scriptable Carbon application.
Use Apple events to communicate with other applications.
Gain background information about Apple events for your work with scriptable Cocoa applications, AppleScript Studio applications, Automator workflows, or AppleScript scripts.

Important: An Apple event can contain object specifiers that identify objects within the application that receives the event. Object specifiers are mentioned only briefly in this document. For information on how to work with object specifiers, see “Resolving and Creating Object Specifier Records” in Inside Macintosh: Interapplication Communication.

Do not rely on the API descriptions in Interapplication Communication—Open Scripting Architecture Reference and Apple Event Manager Reference provide the current API documentation.

Organization of This Document

This document is organized into the following chapters:

“About Apple Events” defines Apple events, explains when they’re useful, and provides a quick overview of common tasks for working with them. It also provides a brief description of the framework and language support available in Mac OS X and provides links to additional information in Apple Events Programming Guide and in other documents.
“Building an Apple Event” provides an overview of Apple event data structures and describes how to build an Apple event.
“Apple Event Dispatching” shows how your application works with the Apple Event Manager to register the Apple events it can handle and dispatch those events to the code that should handle them.
“Working With the Data in an Apple Event” describes how to extract data from Apple events and the data structures that comprise them.
“Responding to Apple Events” describes how to respond to an Apple event by examining the event, performing the requested action, interacting with the user (if necessary), and returning a reply event. It also provides an overview of how to respond to Apple events sent by the Mac OS.
“Creating and Sending Apple Events” provides information and sample code that will help you create and send Apple events and respond to reply Apple events.
“Writing and Installing Coercion Handlers” describes how to write coercion handlers that convert between various types of data and how to install them so that they are available to your application.
“Testing and Debugging Apple Event Code” provides tips for displaying and debugging Apple events in your application.
“Selected Apple Event Manager Functions” provides information about some commonly used functions.
“Selected Apple Event Constants” provides information about some commonly used constants.
“Default Coercion Handlers” lists the type conversions performed by the default coercion handlers provided by the Mac OS.

Introduction to Apple Events Programming Guide

Contents:

Who Should Read This Document

Organization of This Document

See Also