Inside Macintosh: Interapplication Communication /

Chapter 4 - Responding to Apple Events

This chapter describes how your application can use the Apple Event Manager to respond to Apple events. Your application must be able to respond to the four required Apple events to take advantage of the launching and terminating mechanisms that are part of System 7 and later versions of system software. If your application provides publish and subscribe capabilities, it should also handle the events sent by the Edition Manager. To be scriptable, or capable of responding to Apple events sent by scripting components, your application should handle the appropriate core and functional-area Apple events.

Before you read this chapter, you should be familiar with the chapters "Introduction to Interapplication Communication" and "Introduction to Apple Events" in this book. You should also have a copy of the Apple Event Registry: Standard Suites available for reference.

Although the Apple events used by the Edition Manager are discussed in this chapter, you must refer to the chapter "Edition Manager" in this book for a full discussion of how to implement the Edition Manager's publish and subscribe features.

This chapter provides the basic information you need to make your application capable of responding to Apple events. To respond to core and functional-area Apple events, your application must also be able to resolve object specifier records. You should read the chapter "Resolving and Creating Object Specifier Records" before you write Apple event handlers for events that can contain object specifier records.

The section "Handling Apple Events," which begins on page 4-4, describes how to

• accept and process Apple events
• install entries in the Apple event dispatch tables
• handle the required events
• handle events sent by the Edition Manager
• get data out of an Apple event
• write handlers that perform the action requested by an Apple event
• reply to an Apple event
• dispose of Apple event data structures
• write and install coercion handlers

The section "Interacting With the User," which begins on page 4-47, describes

• how a server application can interact with the user when processing an Apple event
• how client applications set user interaction preferences
• how the client application's preferences and the server application's preferences affect user interaction

---

Chapter Contents

Handling Apple Events

Accepting an Apple Event

Installing Entries in the Apple Event Dispatch Tables

Installing Entries for the Required Apple Events

Installing Entries for Apple Events Sent by the Edition Manager

How Apple Event Dispatching Works

Handling the Required Apple Events

Required Apple Events

Handling the Open Application Event

Handling the Open Documents Event

Handling the Print Documents Event

Handling the Quit Application Event

Handling Apple Events Sent by the Edition Manager

The Section Read, Section Write, and Section Scroll Events

Handling the Create Publisher Event

Getting Data Out of an Apple Event

Getting Data Out of an Apple Event Parameter

Getting Data Out of an Attribute

Getting Data Out of a Descriptor List

Writing Apple Event Handlers

Replying to an Apple Event

Disposing of Apple Event Data Structures

Writing and Installing Coercion Handlers

Interacting With the User

Setting the Client Application's User Interaction Preferences

Setting the Server Application's User Interaction Preferences

Requesting User Interaction

Reference to Responding to Apple Events

Data Structures Used by the Apple Event Manager

Descriptor Records and Related Data Structures

Apple Event Array Data Types

Routines for Responding to Apple Events

Creating and Managing the Apple Event Dispatch Tables

Dispatching Apple Events

Getting Data or Descriptor Records Out of Apple Event Parameters and Attributes

Counting the Items in Descriptor Lists

Getting Items From Descriptor Lists

Getting Data and Keyword-Specified Descriptor Records Out of AE Records

Requesting User Interaction

Requesting More Time to Respond to Apple Events

Suspending and Resuming Apple Event Handling

Getting the Sizes and Descriptor Types of Descriptor Records

Deleting Descriptor Records

Deallocating Memory for Descriptor Records

Coercing Descriptor Types

Creating and Managing the Coercion Handler Dispatch Tables

Creating and Managing the Special Handler Dispatch Tables

Getting Information About the Apple Event Manager

Application-Defined Routines

Summary of Responding to Apple Events

Pascal Summary

Constants

Data Types

Routines for Responding to Apple Events

Creating and Managing the Apple Event Dispatch Tables

Dispatching Apple Events

Getting Data or Descriptor Records Out of Apple Event Parameters and Attributes

Counting the Items in Descriptor Lists

Getting Items From Descriptor Lists

Getting Data and Keyword-Specified Descriptor Records Out of AE Records

Requesting User Interaction

Requesting More Time to Respond to Apple Events

Suspending and Resuming Apple Event Handling

Getting the Sizes and Descriptor Types of Descriptor Records

Deleting Descriptor Records

Deallocating Memory for Descriptor Records

Coercing Descriptor Types

Creating and Managing the Coercion Handler Dispatch Tables

Creating and Managing the Special Handler Dispatch Tables

Getting Information About the Apple Event Manager

Application-Defined Routines

C Summary

Constants

Data Types

Routines for Responding to Apple Events

Creating and Managing the Apple Event Dispatch Tables

Dispatching Apple Events

Getting Data or Descriptor Records Out of Apple Event Parameters and Attributes

Counting the Items in Descriptor Lists

Getting Items From Descriptor Lists

Getting Data and Keyword-Specified Descriptor Records Out of AE Records

Requesting User Interaction

Requesting More Time to Respond to Apple Events

Suspending and Resuming Apple Event Handling

Getting the Sizes and Descriptor Types of Descriptor Records

Deleting Descriptor Records

Deallocating Memory for Descriptor Records

Coercing Descriptor Types

Creating and Managing the Coercion Handler Dispatch Tables

Creating and Managing the Special Handler Dispatch Tables

Getting Information About the Apple Event Manager

Application-Defined Routines

Assembly-Language Summary

Trap Macros

Trap Macros Requiring Routine Selectors

Result Codes