NAME

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

SYNOPSIS

        use Mac::AppleEvents;

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. You have been warned.

Constants: Apple event Descriptor Types

typeBoolean

A boolean.

typeTrue

A boolean True value.

typeFalse

A boolean False value.

typeChar

A string.

typeShortInteger

A 16 bit integer.

typeInteger

typeLongInteger

A 32 bit integer.

typeMagnitude

An unsigned 32 bit integer.

typeShortFloat

A single precision floating point number.

typeFloat

typeLongFloat

A double precision floating point number.

typeExtended

An extended double precision floating point number.

typeComp

A 64 bit number.

typeAEList

An Apple event list.

typeAERecord

An Apple event record.

typeAppleEvent

An Apple event.

typeFSS

A file specification record.

typeAlias

A file alias record.

typeEnumerated

An enumeration literal (4 byte character).

typeType

An Apple event type (4 byte character).

typeAppParameters

An application launch parameter record.

typeProperty

A property keyword (4 byte character).

typeKeyword

A keyword (4 byte character).

typeSectionH

An Edition Manager section handle.

typeWildCard

An arbitrary value.

typeApplSignature

An application signature (4 byte character).

typeQDRectangle

A QuickDraw rectangle.

typeFixed

A fixed point value.

typeSessionID

A PPC Toolbox session ID.

typeTargetID

A target ID record.

typeProcessSerialNumber

A process serial number.

typeNull

No data.

Constants: Parameter and Attribute Keywords

keyDirectObject

The direct object parameter.

keyErrorNumber

Error number.

keyErrorString

Error string.

keyProcessSerialNumber

Process serial number.

keyTransactionIDAttr

Transaction ID.

keyReturnIDAttr

Return ID.

keyEventClassAttr

Event class.

keyEventIDAttr

Event ID.

keyAddressAttr

Destination address.

keyOptionalKeywordAttr

List of optional keywords.

keyTimeoutAttr

Timeout limit.

keyInteractLevelAttr

Interaction level.

keyEventSourceAttr

Event source address.

keyMissedKeywordAttr

List of mandatory keywords not used.

keyOriginalAddressAttr

Original source address.

keyPreDispatch

Install handler before dispatching.

keySelectProc

Enable/Disable OSL.

keyAERecorderCount

Number of processes recording AppleEvents.

keyAEVersion

Apple Event Manager version.

Constants: Core Apple event Suite

kCoreEventClass

Core Suite Event class.

kAEOpenApplication

Open application without documents.

kAEOpenDocuments

Open documents.

kAEPrintDocuments

Print documents.

kAEQuitApplication

Quit application.

kAEAnswer

Apple event answer event.

kAEApplicationDied

Launched application has ended.

Constants: Miscellaneous

kAENoReply

kAEQueueReply

kAEWaitReply

kAENeverInteract

kAECanInteract

kAEAlwaysInteract

kAECanSwitchLayer

kAEDontReconnect

kAEWantReceipt

kAEDontRecord

kAEDontExecute

kAEInteractWithSelf

kAEInteractWithLocal

kAEInteractWithAll

Apple event sendMode flags.

kAENormalPriority

kAEHighPriority

Apple event priority values.

kAEStartRecording

kAEStopRecording

kAENotifyStartRecording

kAENotifyStopRecording

kAENotifyRecording

Recording events.

kAutoGenerateReturnID

kAnyTransactionID

kAEDefaultTimeout

kNoTimeOut

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

kAENoDispatch

kAEUseStandardDispatch

kAEDoNotIgnoreHandler

kAEIgnoreAppPhacHandler

kAEIgnoreAppEventHandler

kAEIgnoreSysPhacHandler

kAEIgnoreSysEventHandler

kAEIngoreBuiltInEventHandler

kAEDontDisposeOnResume

Options for AEResumeTheCurrentEvent().

Variables

%AppleEvent

An array of application-wide event handlers.

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

%SysAppleEvent

An arrary of system-wide event handlers.

AEDesc

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

new TYPE, HANDLE

new TYPE, DATA

new TYPE

new

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

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

type TYPE

type

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

data HANDLE

data

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

Warning: If using Mac OS X, you must dispose of the result on your own. This is because in Mac OS, we returned the handle from the AEDesc itself, but now we must return a copy. So in Mac OS we could do:

        print $desc->data->get;

Now we must do:

        my $handle = $desc->data;
        print $handle->get;
        $handle->dispose;

Normally, you don't want to call data directly anyway, and you would use get instead.

get

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

dispose

Dispose the AEDesc.

AEKeyDesc

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

new KEY, TYPE, HANDLE

new KEY, TYPE, DATA

new KEY, TYPE

new KEY

new

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

key KEY

key

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

type TYPE

type

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

data HANDLE

data

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

get

Return the contents in a smartly unpacked way.

dispose

Dispose the underlying AEDesc.

AUTHOR

Written by Matthias Ulrich Neeracher <neeracher@mac.com>, documentation by Bob Dalgleish <bob.dalgleish@sasknet.sk.ca>. Currently maintained by Chris Nandor <pudge@pobox.com>.