aeclass

An four-character code attribute that identifies a group of related Apple events. The event class and the event ID identify the action an Apple event performs. See also aeeventID.

aeeventID

An four-character code attribute that identifies a particular Apple event within a group of related Apple events. The event ID and the event class identify the action an Apple event performs. See also aeclass.

anAddress

An AEAddress, an application name, an application creator code, or TargetID.

coercionHandlerProc

The name of a Tcl proc that will handle the specified AEDesc coercion. The proc must have the following format:

proc coercionHandlerProc {typeCode data toType resultDesc} {
	# convert $data from $typeCode to $toType
	# and return in $resultDesc
}

Note! You must not dispose of resultDesc.

data

Raw ASCII or binary data.

Tcl's "everything is a string" mentality presents complications for conversion to and from the heavily typed world of AppleEvents. After experimenting with a number of different (and unsatisfactory) attempts at automagic conversion, I have settled on the following limited conversions. If you desire anything more elaborate, you can always apply [binary format] and [binary scan] to achieve the desired effect.

input

As an input parameter, data is ASCII unless it was explicitly created as [binary]. As a result, numeric values of data will be sent as a string of ASCII characters. For example, "24.5" will be sent as 0x32342E35. If you desire to send the number itself, use [binary format].

Binary data is sent exactly as is. ASCII data undergoes UTF-to-External encoding conversion.

output

The data returned depends on the final type of the AEDesc:

'TEXT'

the data undergoes External-to-UTF encoding conversion and is returned as a Tcl string object.

'bool'

the data is returned as a Tcl boolean object.

'shor'

the data is returned as a Tcl integer object.

'long'

the data is returned as a Tcl long integer object.

'sing', 'doub'

the data is returned as a Tcl double precision float object.

'list'

the data from AEDescList items are recursively extracted and concatenated in a Tcl list.

all others

the data is returned as raw binary, regardless of type. If the original type is 'reco', expect the return value to be particularly meaningless.

eventHandlerProc

The name of a Tcl proc that will handle the specified AppleEvent. The proc must have the following format:

proc eventHandlerProc {theAppleEvent theReplyAE}
	# Extract any pertinent parameters from $theAppleEvent, 
	# take appropriate action, and return appropriate results
	# in $theReplyAE
}

In addition to manually adding parameters to theReplyAE, the return result of the proc will be added as its '----' direct object. If a direct object has already been added, the proc result is ignored. If no direct object parameter is desired, pass return with no argument to avoid the implicit return value.

If proc throws an error, the error message and code will be entered in the 'errs' and 'errn' parameters of theReplyAE. The 'errs' parameter is taken from the Tcl result as text.

The 'errn' parameter is set from an integer value extracted from

1. the Tcl errorCode, or
2. the second element of a three-element errorCode list, consisting of {{error type} {error number} {error message}}, or
3. the Tcl result.

If no integer error code is found, 'errn' is omitted.

Note! You must not dispose of theReplyAE.

fromType

The DescType to coerce the AEDesc or data from.

desiredType

An optional parameter that holds the DescType to coerce the AEDesc. Omit or pass '****' for no coercion.

index

Numerical index of item in an AEDescList or AERecord.

In the ToolBox, AEDescLists are 1-based, but TclÆ treats them as 0-based for consistency with Tcl lists. When putting into a list, if index is -1 it specifies the end of the list. Negative values of index are an error when getting from a list.

keyIfAnyPtr

An optional parameter that holds the name of a variable which will be set to the keyword of the specified descriptor record if the AEDescList it was obtained from is an AERecord or '****' otherwise.

resultDesc

The AEDesc to hold the coerced data from a coercionHandlerProc. This AEDesc will already exist when your coercion handler proc is called and must not be disposed of by your code.

toType

The DescType to coerce the AEDesc or data to.

theAEDescList

An AEDescList or AERecord.

theAEKeyword

The four-character code keyword of an item in an AERecord.

typeCode

Original DescType associated with data.

theReplyAE

The AEDesc for the reply AppleEvent from an eventHandlerProc. This AEDesc will already exist when your AppleEvent handler proc is called and must not be disposed of by your code.

typeCodePtr

An optional parameter that holds the name of a variable which will be set to the final typeCode of the AEDesc in question.

AEAddress

An AEDesc that describes another process. An AEAddress can be one of:

A Macintosh process serial number

psn («0123456789ABCDEF»)

A remote process

aprl(“eppc://steveo.apple.com/AlphaX”)

A unix process id

kpid(«000004c1»)

Only available on Mac OS X

A bundle id

bund(“net.sourceforge.alphatcl”)

Only available on Panther and above

AEDesc

A hash key tied to an AppleEvent descriptor record.

If your procedure received the AEDesc as an argument, it must not dispose of it.

AEDescList

An AEDesc hash key tied to an AppleEvent descriptor list.

AERecord

An AEDescList hash key tied to an AppleEvent keyed record.

AEGizmo

An AEGizmo is a string in the syntax described by Jens Alfke in the AEGizmos documentation. This is the syntax that Alpha has always(?) used for AppleEvents and is the same that is returned by the Capture AE control panel.

DescType

four-character code defining the data type of an AEDesc.

four-character code

Will be truncated or padded with spaces to exactly four characters.

TargetID

A hash key tied to an AppleEvent target. This target may be on the same machine or located remotely, either on the local AppleTalk network or via AppleTalk-over-IP. The hash key is a text representation of the application name and location.