Thursday, January 28, 1999

This archive can always be obtained from:

    http://www.perl.com/CPAN/authors/id/CNANDOR/
    http://www.perl.com/CPAN/modules/by-module/Mac/

The file is a tarred, gzipped file.  Use Stuffit Expander or a
similar program (like my untargzipme) to get at the archive.

Please let me know how well it does(n't) work, and any changes you'd 
like to see.

#============================================================================

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

    Sending an event with `send_event()' or `do_event()' will check for
    errors automatically, and if there is an error and the `-w' flag is on
    (or `$^W' is nonzero), the error will be sent to `STDERR'. This will
    also only happen if the event return an error in the standard `errn'
    or `errs' keywords. If your app returns errors in another way, you can
    roll your own warning system. This example assumes the direct object
    in the reply is the error if it is a negative integer:

        my $event = do_event( ... );
        my_warn_for_this_app($event);

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

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.

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

            $data = $event->data;   # get an AE list of aliases
            @alis = Mac::AppleEvents::Simple::get($desc);  # get resolved aliases

        The above example is for the case when a list is inside a list. If
        the descriptor in KEY is an AE list, both `get' and `data' will
        return an array of the descriptors or data in list context, and
        the first element in scalar context.

EXPORT
    Exports functions `do_event()', `build_event()', `get_text()'.

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


#============================================================================

-- 
Chris Nandor          mailto:pudge@pobox.com         http://pudge.net/
%PGPKey = ('B76E72AD', [1024, '0824090B CE73CA10  1FF77F13 8180B6B6'])
