Required Apple Events
This section describes the required Apple events-the Apple events your
application must support to be 7.0-friendly-and the descriptor types for all
parameters of the required Apple events. It also describes how to write the
handlers for these events, and it provides sample code.
To support the required Apple events, you must set the necessary flags in the
'SIZE' resource of your application, install entries into your application's
Apple event dispatch table, add code to the event loop of your application to
described in the preceding two sections. You must also write handlers to handle
each Apple event; this section describes how to write these handlers.
When a user opens or prints a file from the Finder, the Finder sets up the
information your application can use to determine which files to open or print.
In version 7.0, if your application supports high-level events, the Finder
communicates this information to your application through the required Apple
events. See Getting Files Selected From the Finder for a code example
showing how to handle these events.
The Finder sends one of the required Apple events to your application to
request that it open or print a list of documents, inform it that the Finder has
just opened your application, or inform it that the Finder is about to terminate
your application.
These are the required Apple events:
Apple event Requested action
Open Application event Perform tasks associated with opening your
application
Open Documents event Open the specified documents
Print Documents event Print the specified documents
Quit Application event Perform tasks-such as releasing memory,
requesting the user to save documents, and so
on- associated with quitting; when appropriate, the
Finder sends this event to an application immediately
after sending it a
Print Documents event or if the user chooses
Restart or Shut Down from the Finder's The Finder uses the required Apple events as part of the new mechanisms in
system 7.0 for launching and terminating applications. This new method of
communicating Finder information to your application replaces the
mechanisms used in earlier versions of system software.
Applications that do not support high-level events can still use the
GetAppParms procedure) to get the Finder information. See the your application 7.0-friendly and compatible with earlier versions of system
software, it must support both the old and new mechanisms.
is present. If it is and the isHighLevelEventAware flag is set in your
application's 'SIZE' resource, your application receives the Finder information
through the required Apple events.
If your application accepts high-level events, the Finder sends it an
Open Application event, Open Documents event, or Print Documents event
immediately after launching your application. Upon receiving any of these
events, your application should perform the action requested by the event.
Note: This section describes the required Apple events as they are sent by the
Finder. When sent by other applications or processes, these same
Apple events-which are among the core Apple events described in the Apple Event Registry-can include optional parameters not listed here. To be
7.0-friendly, your application only needs to handle the required parameters
that are described in this section.
------------------------------------------------------
Open Application event perform tasks associated with opening an
application
Event class kCoreEventClass
Event ID kAEOpenApplication
Parameters None
Requested action Perform any tasks-such as opening an untitled
document window-that you would normally perform
when a user opens your application.
------------------------------------------------------
Open Documents event open the specified documents
Event class kCoreEventClass
Event ID kAEOpenDocuments
Keyword keyDirectObject
Descriptor type typeAEList
Data A list of alias records for the documents to be
opened
Requested action Open the documents specified in the
keyDirectObject parameter.
------------------------------------------------------
Print Documents event print the specified documents
Event class kCoreEventClass
Event ID kAEPrintDocuments
Keyword keyDirectObject
Descriptor type typeAEList
Data A list of alias records for the documents to be
printed
Requested action Print the documents specified in the
keyDirectObject parameter without opening
windows for the documents.
------------------------------------------------------
Quit Application event perform tasks associated with quitting
Event class kCoreEventClass
Event ID kAEQuitApplication
Parameters None
Requested action Perform any tasks that your application would
normally perform when the user chooses Quit. Such
tasks typically include asking the user if he or she
wants to save documents that have been changed.
When appropriate, the Finder sends this event to an
application immediately after sending it a
Print Documents event or if the user chooses
Restart or Shut Down from the Finder's ------------------------------------------------------
Your application needs to recognize only two descriptor types to handle the
required Apple events: descriptor lists and alias records. The
Open Documents event and Print Documents event use descriptor lists to store
a list of documents to open. Each document is specified as an
You can retrieve the data that specifies the document to open as an
alias record to a file system specification (FSSpec) record. The file system specification record provides a standard method of identifying files in version
7.0. See the File Manager description for a complete description of how to specify files using file system specification records.