The building, sending, and disposing is done automatically. The function returns an object containing the parameters. (Previously, the AEPrint results of AEBuildAppleEvent and AESend would be in $event->{EVENT}$event->{REPLY}, but this was wasting way too much memory, as some of these things got big; you can call AEPrint($event->{REP}) yourself).

Also, the Mac::AppleEvents::Simple method will launch the application for you, whereas the Mac::AppleEvents method requires the program to be running already (or launched via Mac::Processes or Mac::Apps::Launch). Launching works only when the target is an app signature or bundle ID.

The raw AEDesc forms are in $event->{EVT} and $event->{REP}. So if I also use'd the Mac::AppleEvents module (or got the symbols via use Mac::AppleEvents::Simple ':all'), I could extract the direct object from the reply like this:

$dobj = AEPrint(AEGetParamDesc($event->{REP}, keyDirectObject));

An easier way to get the direct object data, though, is with the get method, described below.

The sending of the event uses as its defaults (kAEWaitReply, kAENormalPriority, kNoTimeout). To use different parameters, use build_event with send_event.

Setting $Mac::AppleEvents::Simple::SWITCH = 1 forces the target app to go to the front on sending an event to it. This works only when the target is an app signature or bundle ID.

Sending an event with send_event or do_event will check for errors automatically, and if there is an error and $Mac::AppleEvents::Simple::WARN is true, a warning will be sent to STDERR. You can also check $^E after each call, or check the values of $event->{ERRNO} and $event->{ERROR}.

If the event reply itself contains a errn or errs parameter, these will also be placed in $event->{ERRNO} and $event->{ERROR} and $^E as appropriate.

You may decide to roll your own error catching system, too. In this example, the error is returned in the direct object parameter.

This is for delayed execution of the event, or to build an event that will be sent specially with send_event. Build it with build_event, and then send it with send_event method. The parameters are the same as do_event.

Sets up an event handler by passing CLASSID and EVENTID of the event to be handled. If SYS is true, then it sets up a system-wide event handler, instead of an application-wide event handler.

CODE is a code reference that will be passed three parameters: a Mac::AppleEvents::Simple object, the CLASSID, and the EVENTID. The object will work similarly to a regular object. The REP and EVT parameters are switched (that is, you get the event in the REP parameter, and the reply to be sent is in the EVT parameter). This is so the other methods will work just fine, and since you will only be using actual methods on the object and not accessing its data directly, it shouldn't matter, right?

The other difference is that there is an additional data member in the object, called HANDLER, which is for properly disposing of the handler when you are done with it. Your event handler should get disposed of for you in the background.

Similar to get and data from the Mac::AppleEvents module. Get data from a Mac::AppleEvents::Simple object for a given key (keyDirectObject is the default). Can also be called as a function, where an AEDesc object is passed as the first parameter.

For data, if the descriptor in KEY is an AE list, then a list of the descriptors in the list will be returned. In scalar context, only the first element will be returned.

On the other hand, get will return a nested data structure, where all nested AE lists will be converted to perl array references, and all nested AE records will be converted to perl hash references. In scalar context, only the first element of the base list will be returned for AE lists.

Also, get will attempt to convert other data into a more usable form (such as resolving aliases into paths).

Packs a PPC record suitable for using in build_event and do_event. Accepts the 4-character ID of the target app, the name of the app as it may appear in the PPC Chooser, and the server and zone it is on. If not supplied, zone is assumed to be '*'.

Packs an EPPC record suitable for using in build_event and do_event. Accepts the 4-character ID of the target app, the name of the app as it may appear in the PPC Chooser, and the hostname of the machine it is on. Requires Mac OS 9.

Packs an EPPC record suitable for using in build_event and do_event under Mac OS X. Accepts the name of the app, the hostname of the machine it is on, and, optionally, the uid of the owner of the app, the process ID of the app, and the username/password to connect with. Note that it is normally preferable to allow the Keychain to handle the username/password (enter it the first time it is asked for, and select "Add to Keychain?"). Requires Mac OS X.

Note: the UID/PID stuff doesn't actually work for me, in my tests. Huh.