NAME
Mac::AppleEvents::Simple - Simple access to Mac::AppleEvents
SYNOPSIS
#!perl -w
use Mac::AppleEvents::Simple;
use Mac::Files; # for NewAliasMinimal
$alias = NewAliasMinimal(scalar MacPerl::Volumes);
do_event(qw/aevt odoc MACS/, "'----':alis(\@\@)", $alias);
# [...]
use Mac::Errors '$MacError';
use Mac::AppleEvents; # for kAENoReply
$evt = build_event(qw/aevt odoc MACS/, "'----':alis(\@\@)", $alias);
die "There was a problem: $MacError" if $^E;
$evt->send_event(kAENoReply);
die "There was a problem: $MacError" if $^E;
DESCRIPTION
Requirements
For MacPerl 5.2.0r4, you should have the latest cpan-mac distribution:
http://sourceforge.net/projects/cpan-mac/
For MacPerl 5.6.1 and up, everything you need is included.
For Mac OS X, you should have the latest Mac::Carbon:
http://sourceforge.net/projects/macperl/
Also note the differences between MacPerl and perl on Mac OS X listed in Mac::Carbon, especially regarding $^E
.
Overview
This is just a simple way to do Apple Events. The example above was previously done as:
#!perl -w
use Mac::AppleEvents;
use Mac::Files;
$alias = NewAliasMinimal(scalar MacPerl::Volumes);
$evt = AEBuildAppleEvent(qw/aevt odoc sign MACS 0 0/,
"'----':alis(\@\@)", $alias) or die $MacError;
$rep = AESend($evt, kAEWaitReply) or die $MacError;
AEDisposeDesc($rep);
AEDisposeDesc($evt);
The building, sending, and disposing is done automatically. The function returns an object containing the parameters, including the AEPrint
results of AEBuildAppleEvent
$event->{EVENT}
and AESend
$event->{REPLY}
.
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.
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.
my $event = do_event( ... );
die $MacError if $^E; # catch execution errors
my_warn_for_this_app($event); # catch AE reply errors
sub my_warn_for_this_app {
my $event = shift;
my $error = AEGetParamDesc($event->{REP}, keyDirectObject);
if ($error) {
my $err = $error->get;
if ($err =~ /^-\d+$/ && $^W) {
warn "Application error: $err";
}
AEDisposeDesc($error);
}
}
REQUIREMENTS
MacPerl 5.2.0r4 or better, and Mac::Apps::Launch 1.70.
FUNCTIONS
- [$EVENT =] do_event(CLASSID, EVENTID, TARGET, FORMAT, PARAMETERS ...)
-
The first three parameters are required. The FORMAT and PARAMETERS are documented elsewhere; see Mac::AppleEvents and macperlcat.
TARGET may be a four-character app ID or a hashref containing ADDRESSTYPE and ADDRESS. Examples:
{ typeTargetID() => pack_ppc(...) } { typeTargetID() => pack_eppc(...) } { typeProcessSerialNumber() => pack_psn(...) } { typeProcessSerialNumber() => pack_pid(...) }
See the pack functions below for details.
- $EVENT = build_event(CLASSID, EVENTID, TARGET, FORMAT, PARAMETERS ...)
-
This is for delayed execution of the event, or to build an event that will be sent specially with
send_event
. Build it withbuild_event
, and then send it withsend_event
method. The parameters are the same asdo_event
. - $EVENT->send_event([GETREPLY, PRIORITY, TIMEOUT]);
-
For sending events differently than the defaults, which are
kAEWaitReply
,kAENormalPriority
, andkNoTimeout
, or for re-sending an event. The parameters are sticky for a given event, so:$evt->send_event(kAENoReply); $evt->send_event; # kAENoReply is still used
- $EVENT->handle_event(CLASSID, EVENTID, CODE [, SYS]);
-
Note: Untested under Mac OS X. Testing and patches welcome.
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.
An example:
my @data_out; handle_event('CLAS', 'EVNT', \&handler); sub handler { my($evt) = @_; my @data = $evt->get; push @data_out, [$data[0], $data[9]] if $data[0] && $data[9]; } while (1) { if (my $data = shift @data_out) { print "woohoo: @$data\n"; } }
- $EVENT->data([KEY])
- $EVENT->get([KEY])
- data(DESC[, KEY])
- get(DESC[, KEY])
-
Similar to
get
anddata
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). - pack_ppc(ID, NAME, SERVER[, ZONE])
-
Note: Not implemented under Mac OS X.
Packs a PPC record suitable for using in
build_event
anddo_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 '*'. - pack_eppc(ID, NAME, HOST)
-
Note: Not implemented under Mac OS X.
Packs an EPPC record suitable for using in
build_event
anddo_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. - pack_psn(PSN)
-
Simply packs a PSN into a double long.
- pack_pid(PID)
-
Note: Mac OS X only.
Converts a PID into a PSN, then calls
pack_psn
.
EXPORT
Exports functions do_event
, build_event
, handle_event
, pack_ppc
, pack_eppc
, pack_psn
, pack_pid
. All the symbols from Mac::AppleEvents are available in @EXPORT_OK
and through the all
export tag.
AUTHOR
Chris Nandor <pudge@pobox.com>, http://pudge.net/
Copyright (c) 1998-2003 Chris Nandor. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
Mac::AppleEvents, Mac::OSA, Mac::OSA::Simple, macperlcat, Inside Macintosh: Interapplication Communication.
http://projects.pudge.net/
VERSION
v1.05, Thursday, May 22, 2003