Required Events
Volume Number: 10
Issue Number: 12
Column Tag: Getting Started
Related Info: Apple Event Mgr
The Required Apple Events 
Supporting them is easy
By Dave Mark, MacTech Magazine Regular Contributing Author
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
In last month’s column, I told you about a new class library we’ll be using as the
basis for much of the software featured in this column. Ihope to bring you some
Sprocket material starting next month. In the meantime, we’ve gotten a lot of requests
for some code that handles the four required Apple events. That’s what this month’s
column is all about.
The Required Apple Events
In the old days (before System 7), when a user double-clicked on a document, the
Finder first looked up the document’s creator and type in its desktop database to figure
out which application to launch. It then packaged information about the document (or
set of documents if the user double-clicked on more than one) in a data structure,
launched the appropriate application and passed the data structure to the application.
To access this data structure, the application called the routine CountAppFiles() (to
find out how many documents it needs to open or print) then, for each one, it called
GetAppFiles() (to get the information necessary to open the file) and either opened or
printed the file.
That model is no longer supported in the Power Mac interface files. It’s also way
outdated. While existing applications which use the AppFiles method are supported as a
compatibility feature of the system, any new code written these days should support
the current Apple event scheme. When you mark your application as a modern, with-it
application supporting high-level events, launching an application follows a different
path. When a user opens a document, the Finder still uses the file’s creator and type to
locate the right application to launch, but that’s where the similarity ends. Once the
application is launched, the Finder sends it a series of Apple events.
• If the application was launched by itself, with no documents, the Finder sends it
an Open Application Apple event. This tells the application to do its standard
initialization and assume that no documents were opened. In response to an Open
Application Apple event, the application will usually create a new, untitled
document.
• If a document or set of documents were used to launch the application, the Finder
packages descriptions of the documents in a data structure know as a descriptor,
adds the descriptor to an Open Document Apple event, then sends the event to the
application. When the application gets an Open Document event, it pulls the list of
documents from the event and opens each document.
• If the user asked the Finder to print, rather than open a document or set of
documents, the Finder follows the exact same procedure, but sends a Print
Document Apple event instead of an Open Document event. In response to a Print
Document Apple event, the application prints the document rather than opening
it.
• Finally, if the Finder wants an application to quit (perhaps the user selected
Shutdown from the Special menu) it sends the application a Quit Application
Apple event. When the application gets a quit application event, it does whatever
housekeeping it needs to do in preparation for quitting, then sets the global flag
that allows it to drop out of the main event loop and exit.
These events are the four required Apple events. As the name implies, your
application must handle these events. There are a couple of other situations where your
application might receive one of these events.
For starters, any application can package and send an Apple event. If you own a
recent copy of QuicKeys, you’ve got everything you need to build and send Apple events.
If you install AppleScript, you can use the Script Editor to write scripts that get
translated into Apple events. If you make your application recordable (so that the user
can record your application’s actions using the Script Editor, or any other Apple event
recording application) you’ll wrap all of your program’s actions in individual Apple
events. This means that when the user selects Open from the File menu, you’ll send
yourself an Open Document Apple event. If the user quits, you’ll send yourself a Quit
Application event.
In addition to the events described above, there are other situations in which the
Finder will send you one of the four required Apple events. If the user double-clicks on
(or otherwise opens) one of your application’s documents, the Finder will package the
document in an Open Document Apple event and send the event to your application. The
same is true for the Print Document Apple event.
The user can also drag a document onto your application’s icon. If your
application is set up to handle that type of document, your application’s icon will
invert and, when the user let’s go of the mouse, the Finder will embed the document in
an Open Document Apple event and send the event to your application. Note that this
technique can be used to launch your application or to request that your application
open a document once it is already running.
Apple Event Handlers
Apple events are placed in an event queue, much like the events you already
know, love, and process, such as mouseDown, activateEvt, and updateEvt. So far, the
events you’ve been handling have all been low-level events, the direct result of a
user’s actions. The user uncovers a portion of a window, an updateEvt is generated. The
user clicks the mouse button, a mouseDown is generated.
Apple events, on the other hand, are known as high-level events, the result of
interprocess communication instead of user-process communication. As you process
events retrieved by WaitNextEvent(), you’ll take action based on the value in the
event’s what field. If the what field contains the constant updateEvt, you’ll call your