This page describes arguments and types used in TclŽ calls. For information on the associated ToolBox data types, see INSIDE MACINTOSH: Interapplication Communication: Glossary.

• TclŽ arguments
  • aeclass
  • aeeventID
  • anAddress
  • anyAEDesc
  • anyAEDescList
  • asRawBinary
  • coercionHandlerProc
  • data
  • eventHandlerProc
  • fromType
  • desiredType
  • index
  • inPlace
  • keyIfAnyPtr
  • resultDesc
  • theAEDesc
  • toType
  • theAEDescList
  • theAEKeyword
  • theAERecord
  • theAESubDesc
  • typeCode
  • theReplyAE
  • typeCodePtr
• TclŽ types
  • AEDesc
  • AEDescList
  • AERecord
  • AESubDesc
  • AEGizmo
  • DescType
  • four-character code
  • TargetID

TclŽ arguments

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

A TargetID, an application name, or an application creator code.

anyAEDesc

An AEDesc, AESubDesc, or AEGizmo.

anyAEDescList

An AEDescList, AERecord, or an AESubDesc which points to one of those. Never an AEGizmo.

asRawBinary

Optional flag to force the return of raw binary data from an AESubDesc. This is equivalent to passing '????' as the desiredType to tclAE::getData. This is necessary because an AESubDesc is read-only and cannot be coerced.

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.

Alpha 7 users

The Tcl 7.5 interpreter used in Alpha 7.x does not support binary datatypes. TclŽ attempts to simulate them with hexadecimal byte pairs. For example, "\x1a\x2b\x3c\x4d" is represented as "1A2B3C4D". An implementation of the [binary] command is provided that handles this representation. When data is sent as an input parameter, TclŽ must decide whether it is ASCII or pseudobinary. If data consists entirely of an even number of hexadecimal digits, it is taken to be pseudobinary, otherwise it is ASCII. If you get the notion into your pretty little head to pass an ASCII string consisting only of hexadecimal characters, you can ensure proper interpretation by using [binary format a* $data].

eventHandlerProc

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

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

The incoming AppleEvent is passed as an AESubDesc to make access faster and to discourage manipulation.

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.

inPlace

Optional boolean flag. If inPlace is present and true, the new AESubDesc replaces the existing one and is returned with the same hash key. This makes it easy to navigate down through a complex object descriptor record.

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.

theAEDesc

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.

theAERecord

An AERecord.

theAESubDesc

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.

TclŽ types

AEDesc

A hash key tied to an AppleEvent descriptor record.

To avoid a memory leak, you must generally call tclAE::disposeDesc when you are finished with the descriptor record. As a rule, if your procedure created the AEDesc, it is responsible for disposing of it; 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.

AESubDesc

A hash key tied to an AEGizmos AppleEvent subdescriptor record. AESubDescs provide an efficient mechanism for maneuvering through complex AEDesc records without unnecessary duplications. AESubDescs are read-only.

To avoid a memory leak, you must generally call tclAE::subdesc::dispose when you are finished with the sub-descriptor record. As a rule, if your procedure created the AESubDesc, it is responsible for disposing of it; if your procedure received the AESubDesc as an argument, it must not dispose of it.

AEGizmo [descriptor parameters]*

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.

The general usage of descriptor parameters are discussed in the AEGizmos documentation. In TclŽ, each element in the descriptor parameter list is substituted into the AEGizmo string as follows:

• If the AEGizmo string contains a single '@', the corresponding parameter must be the hash key for either an AEDesc or an AESubDesc.
• If the AEGizmo string contains a double "@@", the corresponding parameter is taken as raw data to substitute into the descriptor. The AEBuild parser will insist that the "@@" be coerced to some type, e.g., "TEXT(@@)".

EXAMPLES

 in: tclAE::build "TEXT(@@)" "this is some text"
out: tclAEDesc.1
 in: tclAE::build {[@, sing(@@)]} tclAEDesc.1 [binary format f 3.14159]
out: tclAEDesc.2
 in: tclAE::print tclAEDesc.2
out: [Ňthis is some textÓ, 3.1415901]

Alpha 7 users

'@' substitution with descriptor parameters is not supported.

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.

Copyright Š 1999Đ2000 Jonathan E. Guyer
All rights reserved.