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
The section "Interacting With the User," which begins on page 4-47, describes
- 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
- 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