Monday, September 11, 2000 This is Mac::AppleEvents::Simple, version 1.00. It can always be obtained from the following locations: http://sourceforge.net/projects/mac-ae-simple/ http://www.cpan.org/modules/by-module/Mac/ http://www.cpan.org/authors/id/CNANDOR/ http://pudge.net/macperl/ The file is a tarred, gzipped file. Use Stuffit Expander or a similar program (like untargzipme, in the cpan-mac distribution) to get at the archive. Feedback, patches, bug reports, mailing lists, CVS, etc. are all available at the above SourceForge URL. #============================================================================ 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, TARGET, FORMAT, PARAMETERS ...) The first three parameters are required. The FORMAT and PARAMETERS are documented elsewhere; see the Mac::AppleEvents manpage and the macperlcat manpage. TARGET may be a four-character app ID or a hashref containing ADDRESSTYPE and ADDRESS. For type TARGET, a PPC record can be packed with `pack_ppc'. $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 with `build_event', and then send it with `send_event' method. The parameters are the same as `do_event'. $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->handle_event(CLASSID, EVENTID, CODE [, SYS]); 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' 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). pack_ppc(ID, NAME, SERVER[, ZONE]) 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 '*'. pack_eppc(ID, NAME, HOST) 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. pack_psn(PSN) Simply packs a PSN into a double long. EXPORT Exports functions `do_event', `build_event', `handle_event', `pack_ppc', `pack_eppc', `pack_psn'. All the symbols from Mac::AppleEvents are available in `@EXPORT_OK' and through the `all' export tag. HISTORY v1.00, Monday, September 11, 2000 Added `handle_event' function. Use `cluck' from the Carp module if available if `$WARN' is greater than 1 (fall back to `carp' if `cluck' not available). v0.81, Tuesday, November 2, 1999 Added requirement for Mac::AppleEvents version 1.22 (included in distribution). Added `type' method. Added EPPC addressing (Apple events over TCP/IP). Seems to work as well as the PPC addressing. Requires Mac OS 9. Added `pack_eppc'. v0.80, Friday, September 10, 1999 Added PPC port addressing. Still experimental, as I am working largely off empirical observation, rather than specs. Added `pack_ppc'. (Cameron Ashby ) Added `pack_psn' to simply get a PSN into a long double. v0.72, Wednesday, September 1, 1999 Fixed bug in `_event_error' that did not return proper value, or clear `$^E' properly. (Francis Clarke ) 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 , http://pudge.net/ Copyright (c) 1998-2000 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. http://sourceforge.net/projects/mac-ae-simple/ VERSION v1.00, Monday, September 11, 2000 #============================================================================ -- Chris Nandor pudge@pobox.com http://pudge.net/ Open Source Development Network pudge@osdn.com http://osdn.com/