/ 
Mac-AppleEvents-Simple-0.72
River stage zero No dependents
/ Mac::AppleEvents::Simple

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);
die "There was a problem: $^E" if $^E;
$evt->send_event(kAENoReply);
die "There was a problem: $^E" if $^E;

DESCRIPTION

**NOTE** You should have the Mac::AppleEvents and Mac::Memory distributions from the cpan-mac distribution. See http://pudge.net/macperl/ for more info.

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 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 $^E 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, APPID, FORMAT, PARAMETERS ...)

The first three parameters are required. The FORMAT and PARAMETERS are documented elsewhere; see Mac::AppleEvents and macperlcat.

$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.

$EVENT->send_event([GETREPLY, PRIORITY, TIMEOUT]);
***NOTE***
Previously, you could set $object->{REPLY}.  But REPLY was already
taken.  Whoops.  You now need to set $object->{GETREPLY}.

For sending events differently than the defaults, which are kAEWaitReply, kAENormalPriority, and kNoTimeout, 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->data([KEY])
$EVENT->get([KEY])
data(DESC[, KEY])
get(DESC[, KEY])

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).

EXPORT

Exports functions do_event, build_event.

HISTORY

v0.72, Wednesday, September 1, 1999

Fixed bug in _event_error that did not return proper value, or clear $^E properly. (Francis Clarke <F.Clarke@swansea.ac.uk>)

v0.71, Tuesday, June 8, 1999

Added $DEBUG global. Will be used more.

Added some coercions so certain types will be returned as typeChar from the get method.

v0.70, Friday, June 4, 1999

Removed deprecated ae_send function. Use send_event instead.

Removed deprecated get_text function. Not needed anymore, use get method instead.

Cleaned up stuff.

Improved error handling. Will return on first error. See docs above for more information.

Made $Mac::AppleEvents::Simple::SWITCH 0 by default instead of 1.

Added global %DESCS to save AEDescs for disposal later.

v0.65, May 30, 1999

No longer return entire desc from get if direct object not supplied.

Error number put in $^E if supplied.

Added a bunch of stuff to %AE_GET.

get method now automatically unpacks nested AE records and AE lists into perl hash and array references.

v0.61, May 1, 1999

Made default timeout kNoTimeOut.

Changed use of REPLY for parameter to AESend to GETREPLY. REPLY was already in use, D'oh!

v0.60, January 28, 1999

Added get and data methods.

v0.52, September 30, 1998

Re-upload, sigh.

v0.51, September 29, 1998

Fixed problems accepting parameters in send_event. Sped up switching routine significantly.

v0.50, September 16, 1998

Only LaunchApps when sending event now if $SWITCH is nonzero or app is not already running.

Added warnings for event errors if present and if $^W is nonzero. Only works if event errors use standard keywords errs or errn.

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) 1999 Chris Nandor. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License, distributed with Perl.

SEE ALSO

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

VERSION

v0.72, Wednesday, September 1, 1999