NAME

Mac::AppleEvents::Simple - MacPerl module to do Apple Events more simply

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::AppleEvents;  # for kAENoReply()
$evt = build_event(qw/aevt odoc MACS/, "'----':alis(\@\@)", $alias);
$evt->send_event(kAENoReply());

DESCRIPTION

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 $^E;
$rep = AESend($evt, kAEWaitReply()) or die $^E;
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 used the Mac::AppleEvents module, I could extract the direct object from the reply like this:

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

So you can still mess around with the events if you need to.

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

Setting $Mac::AppleEvents::Simple::SWITCH = 0 prevents target app from going to the front on _send_event().

FUNCTIONS

[$EVENT =] do_event(CLASSID, EVENTID, APPID, FORMAT, PARAMETERS ...)

Documented above. More documentation to come as this thing gets fleshed out more.

$EVENT = build_event(CLASSID, EVENTID, APPID, 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 with build_event(), and then send it with send_event() method. Not sure how useful this is yet.

$EVENT->send_event([REPLY, PRIORITY, TIMEOUT]);

For sending events differntly than the default, which is (kAEWaitReply(), kAENormalPriority(), 3600*9999), or re-sending an event. The parameters are sticky for a given event, so:

$evt->send_event(kAENoReply());
$evt->send_event();  # kAENoReply() is still used

get_text(STRING);

This basically just strips out the curly quotes. It returns the first text in curly quotes it finds in scalar context, and all of them in a list in list context.

EXPORT

Exports functions do_event(), build_event(), get_text().

HISTORY

v0.10, June 2, 1998

Changed new() to build_event(), and ae_send() to send_event().

Made default AESend() parameters overridable via send_event().

v0.03, June 1, 1998

Added $SWITCH global var to override making target app go to front.

v0.02, May 19, 1998

Here goes ...

AUTHOR

Chris Nandor <pudge@pobox.com> http://pudge.net/

Copyright (c) 1998 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. Please see the Perl Artistic License.

SEE ALSO

Mac::AppleEvents, Mac::OSA, Mac::OSA::Simple, macperlcat.