CLIX - Fazer Clix Custa Nix/CLIX-CD.cdr/mac/lib/Mac/AppleEvents.pm

Perl POD Document | 1998-04-05 | 18.4 KB | 911 lines | [TEXT/McPL]

=head1 NAME

Mac::AppleEvents - Macintosh Toolbox Interface to the Apple Event Manager

=head1 SYNOPSIS

    use Mac::AppleEvents;


=head1 DESCRIPTION

Access to Inside Macintosh is essential for proper use of these functions.
Explanations of terms, processes and procedures are provided there.
Any attempt to use these functions without guidance can cause severe errors in
your machine, including corruption of data. B<You have been warned.>

=cut

use strict;

package Mac::AppleEvents;

BEGIN {
    use Exporter   ();
    use DynaLoader ();

    use vars qw(@ISA @EXPORT %AppleEvent %SysAppleEvent);

    @ISA = qw(Exporter DynaLoader);
    @EXPORT = qw(
        AECreateDesc
        AECoerce
        AECoerceDesc
        AEDisposeDesc
        AEDuplicateDesc
        AECreateList
        AECountItems
        AEPut
        AEPutDesc
        AEGetNthDesc
        AEDeleteItem
        AEPutParam
        AEPutParamDesc
        AEGetParamDesc
        AEDeleteParam
        AEGetAttributeDesc
        AEPutAttribute
        AEPutAttributeDesc
        AECreateAppleEvent
        AESend
        AEResetTimer
        AESuspendTheCurrentEvent
        AEResumeTheCurrentEvent
        AEGetTheCurrentEvent
        AESetTheCurrentEvent
        AEGetInteractionAllowed
        AESetInteractionAllowed
        AEInstallEventHandler
        AERemoveEventHandler
        AEGetEventHandler
        AEManagerInfo
        AEBuild
        AEBuildParameters
        AEBuildAppleEvent
        AEPrint
        AEDescToSubDesc
        AEGetSubDescType
        AEGetSubDescBasicType
        AESubDescIsListOrRecord
        AEGetSubDescData
        AESubDescToDesc
        AECountSubDescItems
        AEGetNthSubDesc
        AEGetKeySubDesc

        %AppleEvent
        %SysAppleEvent
        typeBoolean
        typeChar
        typeInteger
        typeFloat
        typeLongInteger
        typeShortInteger
        typeLongFloat
        typeShortFloat
        typeExtended
        typeComp
        typeMagnitude
        typeAEList
        typeAERecord
        typeAppleEvent
        typeTrue
        typeFalse
        typeAlias
        typeEnumerated
        typeType
        typeAppParameters
        typeProperty
        typeFSS
        typeKeyword
        typeSectionH
        typeWildCard
        typeApplSignature
        typeQDRectangle
        typeFixed
        typeSessionID
        typeTargetID
        typeProcessSerialNumber
        typeNull
        keyDirectObject
        keyErrorNumber
        keyErrorString
        keyProcessSerialNumber
        keyTransactionIDAttr
        keyReturnIDAttr
        keyEventClassAttr
        keyEventIDAttr
        keyAddressAttr
        keyOptionalKeywordAttr
        keyTimeoutAttr
        keyInteractLevelAttr
        keyEventSourceAttr
        keyMissedKeywordAttr
        keyOriginalAddressAttr
        keyPreDispatch
        keySelectProc
        keyAERecorderCount
        keyAEVersion
        kCoreEventClass
        kAEOpenApplication
        kAEOpenDocuments
        kAEPrintDocuments
        kAEQuitApplication
        kAEAnswer
        kAEApplicationDied
        kAENoReply
        kAEQueueReply
        kAEWaitReply
        kAENeverInteract
        kAECanInteract
        kAEAlwaysInteract
        kAECanSwitchLayer
        kAEDontReconnect
        kAEWantReceipt
        kAEDontRecord
        kAEDontExecute
        kAENormalPriority
        kAEHighPriority
        kAEStartRecording
        kAEStopRecording
        kAENotifyStartRecording
        kAENotifyStopRecording
        kAENotifyRecording
        kAutoGenerateReturnID
        kAnyTransactionID
        kAEDefaultTimeout
        kNoTimeOut
        kAENoDispatch
        kAEUseStandardDispatch
        kAEDoNotIgnoreHandler
        kAEIgnoreAppPhacHandler
        kAEIgnoreAppEventHandler
        kAEIgnoreSysPhacHandler
        kAEIgnoreSysEventHandler
        kAEIngoreBuiltInEventHandler
        kAEDontDisposeOnResume
        kAEInteractWithSelf
        kAEInteractWithLocal
        kAEInteractWithAll
        kAEUnknownSource
        kAEDirectCall
        kAESameProcess
        kAELocalProcess
        kAERemoteProcess
        kAEDataArray
        kAEPackedArray
        kAEHandleArray
        kAEDescArray
        kAEKeyDescArray
    );
}

bootstrap Mac::AppleEvents;

package Mac::AppleEvents::EventHandler;

BEGIN {
    import Mac::AppleEvents;

    use Carp;
}

sub TIEHASH
{
    my ($package,$sys) = @_;
    my ($me) = bless {SYS => $sys};

    return $me;
}

sub ParseKey
{
    my($key) = @_;

    return (substr($key, 0, 4), substr($key, -4));
}

sub FETCH
{
    my($sys,$key)  = @_;
    my(@keys) = ParseKey $key;

    my ($handler, $refcon) = AEGetEventHandler(@keys, $sys->{SYS});

    return wantarray ? ($handler,$refcon) : $handler;
}


sub STORE
{
    my($sys,$key,$handler,$refcon) = @_;
    my(@keys) = ParseKey $key;

    $refcon = $key unless defined $refcon;

    AEInstallEventHandler(@keys, $handler, $refcon, $sys->{SYS}) || die;
}

sub DELETE
{
    my($sys,$key)  = @_;
    my(@keys) = ParseKey $key;

    AERemoveEventHandler(@keys, $sys->{SYS});
}

sub DESTROY
{
    my($sys)  = @_;

    undef %{$sys};
}

sub FIRSTKEY { croak "Mac::AppleEvents::EventHandler::FIRSTKEY is not implemented" }
sub NEXTKEY { croak "Mac::AppleEvents::EventHandler::NEXTKEY is not implemented" }
sub EXISTS { croak "Mac::AppleEvents::EventHandler::EXISTS is not implemented" }
sub CLEAR { croak "Mac::AppleEvents::EventHandler::CLEAR is not implemented" }

package Mac::AppleEvents;

=head2 Constants: AppleEvent Descriptor Types

=over 4

=item  typeBoolean

A boolean.

=item  typeTrue

A boolean True value.

=item  typeFalse

A boolean False value.

=item  typeChar

A string.

=item  typeShortInteger

A 16 bit integer.

=item  typeInteger

=item  typeLongInteger

A 32 bit integer.

=item  typeMagnitude

An unsigned 32 bit integer.

=item  typeShortFloat

A single precision floating point number.

=item  typeFloat

=item  typeLongFloat

A double precision floating point number.

=item  typeExtended

An extended double precision floating point number.

=item  typeComp

A 64 bit number.

=item  typeAEList

An AppleEvent list.

=item  typeAERecord

An AppleEvent record.

=item  typeAppleEvent

An AppleEvent.

=item  typeFSS

A file specification record.

=item  typeAlias

A file alias record.

=item  typeEnumerated

An enumeration literal (4 byte character).

=item  typeType

An AppleEvent type (4 byte character).

=item  typeAppParameters

An application launch parameter record.

=item  typeProperty

A property keyword (4 byte character).

=item  typeKeyword

A keyword (4 byte character).

=item  typeSectionH

An Edition Manager section handle.

=item  typeWildCard

An arbitrary value.

=item  typeApplSignature

An application signature (4 byte character).

=item  typeQDRectangle

A QuickDraw rectangle.

=item  typeFixed

A fixed point value.

=item  typeSessionID

A PPC Toolbox session ID.

=item  typeTargetID

A target ID record.

=item  typeProcessSerialNumber

A process serial number.

=item  typeNull

No data.

=back

=cut
sub typeBoolean                    {     "bool"; }
sub typeChar                       {     "TEXT"; }
sub typeSMInt                      {     "shor"; }
sub typeInteger                    {     "long"; }
sub typeSMFloat                    {     "sing"; }
sub typeFloat                      {     "doub"; }
sub typeLongInteger                {     "long"; }
sub typeShortInteger               {     "shor"; }
sub typeLongFloat                  {     "doub"; }
sub typeShortFloat                 {     "sing"; }
sub typeExtended                   {     "exte"; }
sub typeComp                       {     "comp"; }
sub typeMagnitude                  {     "magn"; }
sub typeAEList                     {     "list"; }
sub typeAERecord                   {     "reco"; }
sub typeAppleEvent                 {     "aevt"; }
sub typeTrue                       {     "true"; }
sub typeFalse                      {     "fals"; }
sub typeAlias                      {     "alis"; }
sub typeEnumerated                 {     "enum"; }
sub typeType                       {     "type"; }
sub typeAppParameters              {     "appa"; }
sub typeProperty                   {     "prop"; }
sub typeFSS                        {     "fss "; }
sub typeKeyword                    {     "keyw"; }
sub typeSectionH                   {     "sect"; }
sub typeWildCard                   {     "****"; }
sub typeApplSignature              {     "sign"; }
sub typeQDRectangle                {     "qdrt"; }
sub typeFixed                      {     "fixd"; }
sub typeSessionID                  {     "ssid"; }
sub typeTargetID                   {     "targ"; }
sub typeProcessSerialNumber        {     "psn "; }
sub typeNull                       {     "null"; }

=head2 Constants: Parameter and Attribute Keywords

=over 4

=item  keyDirectObject

The direct object parameter.

=item  keyErrorNumber

Error number.

=item  keyErrorString

Error string.

=item  keyProcessSerialNumber

Process serial number.

=item  keyTransactionIDAttr

Transaction ID.

=item  keyReturnIDAttr

Return ID.

=item  keyEventClassAttr

Event class.

=item  keyEventIDAttr

Event ID.

=item  keyAddressAttr

Destination address.

=item  keyOptionalKeywordAttr

List of optional keywords.

=item  keyTimeoutAttr

Timeout limit.

=item  keyInteractLevelAttr

Interaction level.

=item  keyEventSourceAttr

Event source address.

=item  keyMissedKeywordAttr

List of mandatory keywords not used.

=item  keyOriginalAddressAttr

Original source address.

=item  keyPreDispatch

Install handler before dispatching.

=item  keySelectProc

Enable/Disable OSL.

=item  keyAERecorderCount

Number of processes recording AppleEvents.

=item  keyAEVersion

AppleEvent Manager version.

=back

=cut
sub keyDirectObject                {     "----"; }
sub keyErrorNumber                 {     "errn"; }
sub keyErrorString                 {     "errs"; }
sub keyProcessSerialNumber         {     "psn "; }
sub keyTransactionIDAttr           {     "tran"; }
sub keyReturnIDAttr                {     "rtid"; }
sub keyEventClassAttr              {     "evcl"; }
sub keyEventIDAttr                 {     "evid"; }
sub keyAddressAttr                 {     "addr"; }
sub keyOptionalKeywordAttr         {     "optk"; }
sub keyTimeoutAttr                 {     "timo"; }
sub keyInteractLevelAttr           {     "inte"; }
sub keyEventSourceAttr             {     "esrc"; }
sub keyMissedKeywordAttr           {     "miss"; }
sub keyOriginalAddressAttr         {     "from"; }
sub keyPreDispatch                 {     "phac"; }
sub keySelectProc                  {     "selh"; }
sub keyAERecorderCount             {     "recr"; }
sub keyAEVersion                   {     "vers"; }

=head2 Constants: Core AppleEvent Suite

=over 4

=item  kCoreEventClass

Core Suite Event class.

=item  kAEOpenApplication

Open application without documents.

=item  kAEOpenDocuments

Open documents.

=item  kAEPrintDocuments

Print documents.

=item  kAEQuitApplication

Quit application.

=item  kAEAnswer

AppleEvent answer event.

=item  kAEApplicationDied

Launched application has ended.

=back

=cut
sub kCoreEventClass                {     "aevt"; }
sub kAEOpenApplication             {     "oapp"; }
sub kAEOpenDocuments               {     "odoc"; }
sub kAEPrintDocuments              {     "pdoc"; }
sub kAEQuitApplication             {     "quit"; }
sub kAEAnswer                      {     "ansr"; }
sub kAEApplicationDied             {     "obit"; }

=head2 Constants: Miscellaneous

=over 4

=item  kAENoReply

=item  kAEQueueReply

=item  kAEWaitReply

=item  kAENeverInteract

=item  kAECanInteract

=item  kAEAlwaysInteract

=item  kAECanSwitchLayer

=item  kAEDontReconnect

=item  kAEWantReceipt

=item  kAEDontRecord

=item  kAEDontExecute

=item  kAEInteractWithSelf

=item  kAEInteractWithLocal

=item  kAEInteractWithAll

AppleEvent sendMode flags.

=cut
sub kAENoReply                     { 0x00000001; }
sub kAEQueueReply                  { 0x00000002; }
sub kAEWaitReply                   { 0x00000003; }
sub kAENeverInteract               { 0x00000010; }
sub kAECanInteract                 { 0x00000020; }
sub kAEAlwaysInteract              { 0x00000030; }
sub kAECanSwitchLayer              { 0x00000040; }
sub kAEDontReconnect               { 0x00000080; }
sub kAEWantReceipt                 { 0x00000200; }
sub kAEDontRecord                  { 0x00001000; }
sub kAEDontExecute                 { 0x00002000; }
sub kAEInteractWithSelf            {          0; }
sub kAEInteractWithLocal           {          1; }
sub kAEInteractWithAll             {          2; }

=item  kAENormalPriority

=item  kAEHighPriority

AppleEvent priority values.

=cut
sub kAENormalPriority              { 0x00000000; }
sub kAEHighPriority                { 0x00000001; }

=item  kAEStartRecording

=item  kAEStopRecording

=item  kAENotifyStartRecording

=item  kAENotifyStopRecording

=item  kAENotifyRecording

Recording events.

=cut
sub kAEStartRecording              {     "reca"; }
sub kAEStopRecording               {     "recc"; }
sub kAENotifyStartRecording        {     "rec1"; }
sub kAENotifyStopRecording         {     "rec0"; }
sub kAENotifyRecording             {     "recr"; }

=item  kAutoGenerateReturnID

=item  kAnyTransactionID

=item  kAEDefaultTimeout

=item  kNoTimeOut

Special values for return ID, transaction ID, and timeout.

=cut
sub kAutoGenerateReturnID          {         -1; }
sub kAnyTransactionID              {          0; }
sub kAEDefaultTimeout              {         -1; }
sub kNoTimeOut                     {         -2; }

=item  kAENoDispatch

=item  kAEUseStandardDispatch

=item  kAEDoNotIgnoreHandler

=item  kAEIgnoreAppPhacHandler

=item  kAEIgnoreAppEventHandler

=item  kAEIgnoreSysPhacHandler

=item  kAEIgnoreSysEventHandler

=item  kAEIngoreBuiltInEventHandler

=item  kAEDontDisposeOnResume

Options for C<AEResumeTheCurrentEvent()>.

=cut
sub kAENoDispatch                  {          0; }
sub kAEUseStandardDispatch         { 0xFFFFFFFF; }
sub kAEDoNotIgnoreHandler          { 0x00000000; }
sub kAEIgnoreAppPhacHandler        { 0x00000001; }
sub kAEIgnoreAppEventHandler       { 0x00000002; }
sub kAEIgnoreSysPhacHandler        { 0x00000004; }
sub kAEIgnoreSysEventHandler       { 0x00000008; }
sub kAEIngoreBuiltInEventHandler   { 0x00000010; }
sub kAEDontDisposeOnResume         { 0x80000000; }

sub kAEUnknownSource               {          0; }
sub kAEDirectCall                  {          1; }
sub kAESameProcess                 {          2; }
sub kAELocalProcess                {          3; }
sub kAERemoteProcess               {          4; }
sub kAEDataArray                   {          0; }
sub kAEPackedArray                 {          1; }
sub kAEHandleArray                 {          2; }
sub kAEDescArray                   {          3; }
sub kAEKeyDescArray                {          4; }

=back

=head2 Variables

=over 4

=item %AppleEvent

An array of application-wide event handlers.

   $AppleEvent{"aevt", "odoc"} = \&OpenDocument;

=item %SysAppleEvent

An arrary of system-wide event handlers.

=back

=cut
tie %AppleEvent,    q(Mac::AppleEvents::EventHandler), 0;
tie %SysAppleEvent, q(Mac::AppleEvents::EventHandler), 1;

my(%constant) = (
    "true" => 1,
    "fals" => 0,
    "null" => "",
);

package AEDesc;

=head2 AEDesc

AEDesc is a Perl package that encapsulates an AppleEvent Descriptor.
It uses the OO methods of Perl5 to make building and parsing data structures
easier.

=item new TYPE, HANDLE

=item new TYPE, DATA

=item new TYPE

=item new

Create a new AppleEvent descriptor.
Sets the type and data to TYPE (default is 'null'), and HANDLE or DATA
(default is empty).

    $desc = new AEDesc("aevt", $event);

=item type TYPE

=item type

Return the type from the AEDesc structure.
If TYPE is present, make it the new type.

=item data HANDLE

=item data

Return the data from the AEDesc structure. If HANDLE is present, make
it the new data.

=item get

Return the data of the AEDesc structure in a smartly unpacked way.

=back

=cut

BEGIN {
    use Mac::Memory ();
    use Mac::Types;
}

sub new {
    my($package, $type, $data) = @_;

    if (defined($data) && ref($data) ne "Handle") {
        _new($package, $type, new Handle($data));
    } else {
        _new(@_);
    }
}

sub get () {
    my($desc) = @_;
    my($type) = $desc->type;

    if (exists($constant{$type})) {
        return $constant{$type};
    } elsif (exists($MacUnpack{$type})) {
        return MacUnpack($type, $desc->data->get);
    } else {
        return &Mac::AppleEvents::AEPrint($desc);
    }
}

package AESubDesc;

BEGIN {
    use Mac::Memory ();
    use Mac::Types;
    import Mac::AppleEvents;
}

sub get () {
    my($desc) = @_;
    my($type) = AEGetSubDescType($desc);

    if (exists($constant{$type})) {
        return $constant{$type};
    } elsif (exists($MacUnpack{$type})) {
        return MacUnpack($type, AEGetSubDescData($desc));
    } else {
        my($aedesc,$res) = AESubDescToDesc($desc);
        $res = AEPrint($aedesc);
        AEDisposeDesc($aedesc);

        return $res;
    }
}

package AEKeyDesc;

=head2 AEKeyDesc

AEKeyDesc is a Perl package that encapsulates an AppleEvent keyword.
It uses the OO methods of Perl5 to make building and parsing data structures
easier.

=item new KEY, TYPE, HANDLE

=item new KEY, TYPE, DATA

=item new KEY, TYPE

=item new KEY

=item new

Creates a new AppleEvent keyword descriptor.
Sets the keyword, type and data to KEY (default is zero),
TYPE (default is 'null'), and HANDLE or DATA (default is empty).

=item key KEY

=item key

Return the keyword of the AEKeyDesc structure.
If KEY is present, make it the new keyword.

=item type TYPE

=item type

Return the type from the AEKeyDesc structure.  If TYPE is present, make it the new type.

=item data HANDLE

=item data

Return the data from the AEKeyDesc structure. If HANDLE is present, make
it the new data.

=item get

Return the contents in a smartly unpacked way.

=back

=cut

sub new {
    my($package, $key, $type, $data) = @_;

    if (defined($data) && ref($data) ne "Handle") {
        _new($package, $key, $type, new Handle($data));
    } else {
        _new(@_);
    }
}

package AEStream;

sub new {
    my($package) = shift @_;

    if (!scalar(@_)) {
        Open();
    } elsif (scalar(@_) == 1) {
        OpenEvent(@_);
    } else {
        CreateEvent(@_);
    }
}

=include AppleEvents.xs

=head1 AUTHOR

Matthias Ulrich Neeracher [e-mail] "Programs"

Bob Dalgleish [e-mail] "Documentation"

=cut
1;

__END__