jkc@apple.com (John Kevin Calhoun) (05/25/91)
When HyperCard 2.1 receives an Apple event, it sends an appleEvent
message to the current card. That means that you can respond to Apple
events with HyperTalk scripts. But before you try to write such scripts,
there are some terms and conventions you should be familiar with.
The figure
----------
Apple events are like a package full of raw materials that arrive at a
factory. They have a return address on them -- in HyperTalk, a string of
the form "Zone:Macintosh:Program". They have an explanation of what their
contents are for -- the class and id, which together consititute a verb,
directing the receiver what do to with the package. And of course there
are the contents themselves -- the event parameters.
When you get one of these packages, you have to unpack it before you can
make something out of the raw materials inside. But you can't just rip
into the package willy-nilly. You have to ask for what you want, by name.
"Give me the snod." "OK, now give me the lerd." You unpack the contents,
one by one, and make out of them whatever you're directed to make by the
class and id.
The catch is that the package doesn't come with a packing list. You're
supposed to know what's in it -- you have a big book that tells you that
whenever you get a package that you're supposed to make into a "wild plum",
it's supposed to have a "bork", a "flam", and a "nitz" inside of it. So
you unpack the bork, the flam, and the nitz, and then you make the wild
plum out of them and send it back.
Apple event = package
class and id = terse directions for what to do with the package
parameters = contents of the package
keywords = names for each thing in the package
The lesson
----------
In HyperTalk, when you handle the appleEvent message, you first look at
the class and id, and they tell you what you're supposed to do with the
event. If it's an event that you know how to handle, you already know what
the parameters are -- you've agreed with the sender in advance on what's
supposed to be in it, or it's a standard Apple event defined in the
voluminous standard documentation. So you unpack the parameters with the
"request" command, manipulate them, and send back what you made out of them
with the "reply" command.
The script might look like this:
on appleEvent class,id,sender
if class & id is "wildplum" then
request ae data with keyword "bork"
if the result is not empty then -- probably "Not found"
reply error "Expected a bork but got none."
exit appleEvent
end if
put it into theBork
request ae data with keyword "flam"
.
.
.
.
get wildPlumMakingFunction(theBork,theFlam,theNitz) -- process it
reply it -- send back the reply
else pass appleEvent -- we don't recognize this event; pass it on
end appleEvent
Keywords
--------
Think of a keyword for a piece of data in the package as its name -- it's
the handle you need to pull it out of the package. Asking for a parameter
by keyword is the same as asking for a piece of raw material by name.
Keywords are arbitrary. Whoever invents an Apple event makes them up, on
the spot, out of the blue, to name the pieces of data that go along with
the event. The standard Apple events that have already been defined, along
with the keywords for their required and optional parameters, are described
in the Apple Event Registry.
The direct object
-----------------
Many Apple events arrive with just one piece of raw material in them, or
one piece that's more important than the others. By convention, this piece
is given the keyword "----" and is referred to in the Apple event
documenation as "the direct object" or "the direct parameter". These are
pretty ugly names, so in HyperTalk you can just call it the "data" and
leave off the keyword specification -- HyperCard will know what you're
talking about.
request appleEvent data
This is equivalent to the following statement.
request appleEvent data of keyword "----"
The direct object for the 'odoc' event is the list of documents to open.
The direct object for the 'dosc' event is the script to execute. And so
on.
Event attributes
----------------
Apple events come along with more than just an address, a verb, and pieces
of data. They also come with modifiers, or "attributes", which you can
think of as "special handling instructions". The class, id, and sender are
all attributes also, but HyperCard gives you these automatically as
parameters to the appleEvent message. The timeout value, the transaction
id, and the return id -- the identifier you put on the reply so that the
sender knows, when his wild plum arrives, which package you made it out of
-- are additional attributes. If you need to look at these, the "request"
command will let you.
You can get the return id,
request appleEvent return id
request appleEvent data of keyword "rtid" -- same thing, only uglier
the timeout value,
request appleEvent data of keyword "timo"
the transaction id,
request appleEvent data of keyword "tran"
and whatever else you think you need, as long as you know its keyword. We
have special forms of the request command for the class, id, sender, direct
object, and return id -- for everything else, you have to tell HyperCard
what you want by keyword.
request appleEvent class -- gives you the class attribute
request appleEvent id -- gives you the id attribute
request appleEvent sender -- gives you the sender attribute
request appleEvent data -- gives you the direct object parameter
request appleEvent return id -- gives you the return id attribute
Kevin Calhoun
jkc@apple.com