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

There are a plethora of routines in these packages, and the majority of the parsing routines, in particular, will probably never be called directly. The ones most programmers will ever have need to call are listed below.

Note: If you do have reason to parse some sub-string of an AEDesc, keep in mind that, with the exception of tclAE::parse::event, all of the token and grammar parsers operate in place, i.e., they are not passed a string, but the name of a string and, when finished, the parsed material is removed from the start of the string.

namespace tclAE

tclAE::build

SYNOPSIS

RESULT

Hash key for new AEDesc.

DESCRIPTION

Tcl wrapper for AEGizmos' AEBuild. (NOTE! This is not to be confused with Alpha's old (and still existing) AEBuild call. Pete combined the functions of AEBuild and AESend, but it now makes sense to distinguish them.)

<AEGizmos> is a string in the syntax described by Jens Alfke in the AEGizmos documentation. This is the syntax that Alpha has always used 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 AEGizmos strings as follows:

• If the AEGizmo string contains a single '@', the parameter must be the hash key for either an AEDesc or an AESubDesc.
• If the AEGizmo string contains a double "@@", the 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(@@)".

tclAE::print

Tcl wrapper for AEGizmos AEPrint call.

SYNOPSIS

tclAE::print <theAEDesc>

RESULT

AEGizmo string representation of theAEDesc.

DESCRIPTION

theAEDesc can be an AEDesc hash key, an AESubDesc hash key, or an AEGizmo string (with optional '@' parameters (see tclAE::build)).

tclAE::PPCBrowser

SYNOPSIS

DESCRIPTION

Tcl wrapper for ToolBox PPCBrowser call. Produces a TargetID and returns a hash key for later access.

Flags are:

-p <string>

Prompt string

-l <string>

Label for application pane

-fc <list>

Creator-type list

-fn <list>

Port name list

tclAE::send

SYNOPSIS

DESCRIPTION

-r

direct reply requested

-q

queued reply requested (register handler with currentReplyHandler)

-p

print reply with AEPrint before returning it (if absent, return parsed AEDesc identifier).

-t <timeout>

specifies event timeout in ticks

tclAE::target

SYNOPSIS

DESCRIPTION

tclAE::target info <target> <array>

Given a target name, creates an array called 'array' in the current context, containing fields 'nameScript', 'name', 'portKindSelector', and 'locationKindSelector'. If 'portKindSelector' is 'ppcByCreatorAndType', there will be additional fields 'portCreator' and 'portType'. If 'portKindSelector' is 'ppcByString', there will be an additional field 'portTypeStr'.

tclAE::target names

Returns list of all available targets.

tclAE::target set <target> <keyword> <value>

Set keyword element of target to value.

namespace tclAE::desc

tclAE::desc::coerce

Tcl wrapper for ToolBox AECoerceDesc call.

SYNOPSIS

tclAE::desc::coerce <theAEDesc> <toType>

RESULT

Hash key for new AEDesc.

DESCRIPTION

Create a new AEDesc, casting the original theAEDesc to toType.

theAEDesc can be an AEDesc hash key, an AESubDesc hash key, or an AEGizmo string (with no '@' parameters).

tclAE::desc::coerceData

Tcl wrapper for ToolBox AECoercePtr call.

SYNOPSIS

tclAE::desc::coerceData <typeCode> <data> <toType>

RESULT

Hash key for new AEDesc.

DESCRIPTION

Create a new AEDesc, casting data from typeCode to toType. Unlike the ToolBox call, it doesn't really mean anything to pass a pointer in Tcl, so pass the data directly.

tclAE::desc::countItems

Tcl wrapper for ToolBox AECountItems (or AEGizmos AECountSubDescItems) call.

SYNOPSIS

tclAE::desc::countItems <theAEDescList>

RESULT

The number of items in <theAEDescList>.

DESCRIPTION

Count items in <theAEDescList> or throw an error if <theAEDescList> isn't a hash key for an AEDescList, AERecord, or AESubDesc.

Note: theAEDescList cannot be an AEGizmo string.

tclAE::desc::create

Tcl wrapper for ToolBox AECreateDesc call.

SYNOPSIS

tclAE::desc::create <typeCode> ¿data?

RESULT

Hash key for new AEDesc.

DESCRIPTION

Create a new AEDesc of type typeCode with optional data.

tclAE::desc::createList

Tcl wrapper for ToolBox AECreateList call.

SYNOPSIS

tclAE::desc::createList ¿isRecord?

RESULT

Hash key for new AEDescList.

tclAE::desc::deleteItem

Tcl wrapper for ToolBox AEDeleteItem call.

SYNOPSIS

tclAE::desc::deleteItem <theAEDescList> <item>

RESULT

None.

DESCRIPTION

Delete decriptor record at position <item> from theAEDescList (or theAERecord).

In the ToolBox, AEDescLists are 1-based, but TclÆ treats them as 0-based for consistency with Tcl lists.

tclAE::desc::deleteKey

Tcl wrapper for ToolBox AEDeleteKeyDesc call.

SYNOPSIS

tclAE::desc::deleteKey <theAERecord> <theAEKeyword>

RESULT

None.

DESCRIPTION

Delete item with key <theAEKeyword> from theAERecord.

tclAE::desc::dispose

Tcl wrapper for ToolBox AEDisposeDesc call.

SYNOPSIS

tclAE::desc::dispose <theAEDesc>

RESULT

None.

DESCRIPTION

<theAEDesc> is disposed of and its hash key is deleted.

tclAE::desc::duplicate

Tcl wrapper for ToolBox AEDuplicateDesc call.

SYNOPSIS

tclAE::desc::duplicate <theAEDesc>

RESULT

Hash key for duplicate AEDesc.

DESCRIPTION

<theAEDesc> is duplicated and the new AEDesc is entered into the hash table.

theAEDesc can be an AEDesc hash key, an AESubDesc hash key, or an AEGizmo string (with optional '@' parameters (see tclAE::build)).

tclAE::desc::getData

Tcl access for theAEDesc.dataHandle.

SYNOPSIS

tclAE::desc::getData <theAEDesc> ¿desiredType? ¿typeCodePtr?

RESULT

Text representation of theAEDesc.

DESCRIPTION

<theAEDesc> is cast to desiredType (if supplied). The data returned depends on the final type of the AEDesc:

'list'

the AEDescList items are recursively cast to text and concatenated in a Tcl list.

'bool'

the data is returned as boolean 0 or 1.

all others

the AEDesc is cast to 'TEXT'. This puts most types of data in a form that's useful to Tcl. Whether or not the coercion succeeds, the binary data is returned.

If supplied, typeCodePtr is the name of a variable which will be set to the coerced TypeCode of theAEDesc.

tclAE::desc::getKey

Tcl wrapper for ToolBox AEGetKeyDesc call.

SYNOPSIS

tclAE::desc::getKey <theAERecord> <theAEKeyword> ¿desiredType?

RESULT

Hash key pointing to key descriptor.

DESCRIPTION

The key record specified by theAEKeyword is obtained from theAERecord, optionally coerced to desiredType, duplicated, and a new hash key is returned for it.

tclAE::desc::getKeyData

Tcl emulator for ToolBox AEGetKeyPtr call.

SYNOPSIS

tclAE::desc::getKeyData <theAERecord> <theAEKeyword> ¿desiredType? ¿typeCodePtr?

RESULT

Text representation of theAERecord key item.

DESCRIPTION

The key record specified by theAEKeyword is obtained from theAERecord. The resulting AEDesc is coerced to desiredType (if supplied) and then processed as by tclAE::desc::getData.

If supplied, typeCodePtr is the name of a variable which will be set to the coerced TypeCode of theAEDesc.

tclAE::desc::getKeyGizmo

Alternative Tcl wrapper for ToolBox AEGetKeyDesc call.

SYNOPSIS

tclAE::desc::getKeyGizmo <theAERecord> <theAEKeyword> ¿desiredType?

RESULT

AEGizmo string representation of the key descriptor.

DESCRIPTION

The key record specified by theAEKeyword is obtained from theAERecord, optionally coerced to desiredType, and then passed through AEPrint.

tclAE::desc::getNth

Tcl wrapper for ToolBox AEGetNthDesc call.

SYNOPSIS

tclAE::desc::getNth <theAEDescList> <index> ¿desiredType? 
¿theAEKeyword?

RESULT

Hash key pointing to item descriptor.

DESCRIPTION

The item record specified by item is obtained from theAEDescList. The resulting AEDesc is optionally coerced to desiredType, duplicated, and a new hash key is returned for it.

In the ToolBox, AEDescLists are 1-based, but TclÆ treats them as 0-based for consistency with Tcl lists.

If supplied, theAEKeywordPtr is the name of a variable which will be set to the keyword of the specified descriptor record if theAEDescList is an AERecord or '****' otherwise.

tclAE::desc::getNthData

Tcl emulator for ToolBox AEGetNthPtr call.

SYNOPSIS

tclAE::desc::getNthData <theAEDescList> <index> ¿desiredType? 
¿theAEKeyword? ¿typeCodePtr?

RESULT

Text representation of the data from the descriptor record at position item in theAEDescList.

DESCRIPTION

The item record specified by item is obtained from theAEDescList. The resulting AEDesc is coerced to desiredType (if supplied) and then processed as by tclAE::desc::getData.

In the ToolBox, AEDescLists are 1-based, but TclÆ treats them as 0-based for consistency with Tcl lists.

If supplied, theAEKeywordPtr is the name of a variable which will be set to the keyword of the specified descriptor record if theAEDescList is an AERecord or '****' otherwise.

If supplied, typeCodePtr is the name of a variable which will be set to the descriptor type of the returned descriptor record.

tclAE::desc::getNthGizmo

Alternative Tcl wrapper for ToolBox AEGetNthDesc call.

SYNOPSIS

tclAE::desc::getNthGizmo <theAEDescList> <index> ¿desiredType? 
¿theAEKeyword?

RESULT

AEGizmo string representation of the item descriptor.

DESCRIPTION

The item record specified by item is obtained from theAEDescList. The resulting AEDesc is optionally coerced to desiredType, and then passed through AEPrint.

In the ToolBox, AEDescLists are 1-based, but TclÆ treats them as 0-based for consistency with Tcl lists.

If supplied, theAEKeywordPtr is the name of a variable which will be set to the keyword of the specified descriptor record if theAEDescList is an AERecord or '****' otherwise.

tclAE::desc::getType

Tcl access for theAEDesc.descriptorType.

SYNOPSIS

tclAE::desc::getType <theAEDesc>

RESULT

The DescType of theAEDesc.

DESCRIPTION

The FourCharCode type of theAEDesc is cast to a string and returned.

tclAE::desc::listDescriptors

List the active AEDesc hash keys.

SYNOPSIS

tclAE::desc::listDescriptors

RESULT

List of AEDesc hash keys.

DESCRIPTION

The hash keys for the active AEDescs are compiled and returned in a Tcl list.

tclAE::desc::putNth

Tcl wrapper for ToolBox AEPutDesc call.

SYNOPSIS

tclAE::desc::putNth <theAEDescList> <index> <theAEDesc>

RESULT

None.

DESCRIPTION

The item record specified by item in theAEDescList is replaced with theAEDesc.

In the ToolBox, AEDescLists are 1-based, but TclÆ treats them as 0-based for consistency with Tcl lists.

theAEDesc can be an AEDesc hash key, an AESubDesc hash key, or an AEGizmo string (with optional '@' parameters (see tclAE::build)).

tclAE::desc::putNthData

Tcl emulator for ToolBox AEPutPtr call.

SYNOPSIS

tclAE::desc::putNthData <theAEDescList> <index> <typeCode> 
<data>

RESULT

None.

DESCRIPTION

The item record specified by item in theAEDescList is replaced with a new descriptor record composed from data cast to typeCode.

In the ToolBox, AEDescLists are 1-based, but TclÆ treats them as 0-based for consistency with Tcl lists.

tclAE::desc::putKey

Tcl wrapper for ToolBox AEPutKeyDesc call.

SYNOPSIS

tclAE::desc::putKey <theAERecord> <theAEKeyword> 
<theAEDesc>

RESULT

None.

DESCRIPTION

The key record specified by theAEKeyword in theAERecord is replaced with theAEDesc.

theAEDesc can be an AEDesc hash key, an AESubDesc hash key, or an AEGizmo string (with optional '@' parameters (see tclAE::build)).

tclAE::desc::putKeyData

Tcl emulator for ToolBox AEPutKeyPtr call.

SYNOPSIS

tclAE::desc::putKeyData <theAERecord> <theAEKeyword> 
<typeCode> <data>

RESULT

None.

DESCRIPTION

The key record specified by theAEKeyword in theAERecord is replaced with a new descriptor record composed from data cast to typeCode.

namespace tclAE::subdesc

tclAE::subdesc::dispose

Dispose of an AESubDesc.

SYNOPSIS

tclAE::subdesc::dispose <theAESubDesc>

RESULT

None.

DESCRIPTION

<theAESubDesc> is deleted and its hash key is removed from the AESubDesc hash table.

Note: The underlying AEDesc is not disposed of. That would be Bad.

Note: This Tcl proc has no analogue in the AEGizmos API. AESubDescs are not normally allocated, so they don't need to be disposed of. This proc is needed because of the way hashes work in Tcl.

tclAE::subdesc::fromDesc

Tcl wrapper for AEGizmos AEDescToSubDesc call.

SYNOPSIS

tclAE::subdesc::fromDesc <theAEDesc>

RESULT

Hash key for new AESubDesc.

DESCRIPTION

Create a new AESubDesc, pointing at the supplied AEDesc.

tclAE::subdesc::getBasicType

Tcl wrapper for AEGizmos AEGetSubDescBasicType call.

SYNOPSIS

tclAE::subdesc::getBasicType <theAESubDesc>

RESULT

Basic type of theAESubDesc.

DESCRIPTION

This proc returns the same value as tclAE::getSubDescType, with one exception; if the sub-descriptor is a coerced record, the type returned is 'reco'.

tclAE::subdesc::getData

Tcl wrapper for AEGizmos AEGetSubDescData call.

SYNOPSIS

tclAE::subdesc::getData <theAESubDesc>

RESULT

Text representation of theAESubDesc key item.

DESCRIPTION

The descriptor record pointed at by theAESubDesc is processed as by tclAE::desc::getData.

tclAE::subdesc::getKey

Tcl wrapper for AEGizmos AEGetKeySubDesc call.

SYNOPSIS

tclAE::subdesc::getKey <theAESubDesc> <theAEKeyword> 
¿inPlace?

RESULT

Hash key for new AESubDesc.

DESCRIPTION

The key record specified by theAEKeyword is obtained from theAERecord belonging to theAESubDesc.

If inPlace is true (default false), the new AESubDesc replaces theAESubDesc and is returned with the same hash key.

tclAE::subdesc::getKeyData

Convenience access to data of AEGetKeySubDesc.

SYNOPSIS

tclAE::subdesc::getKeyData <theAESubDesc> <theAEKeyword>

RESULT

Text representation of theAESubDesc key item.

DESCRIPTION

The key record specified by theAEKeyword is obtained from theAERecord pointed at by theAESubDesc. The resulting AEDesc is processed as by tclAE::desc::getData.

tclAE::subdesc::getNth

Tcl wrapper for AEGizmos AEGetNthSubDesc call.

SYNOPSIS

tclAE::subdesc::getNth <theAESubDesc> <index> 
¿keyIfAnyPtr? ¿inPlace?

RESULT

Hash key for new AESubDesc.

DESCRIPTION

The descriptor record at position index is obtained from theAEDescList belonging to theAESubDesc.

In the ToolBox, AEDescLists are 1-based, but TclÆ treats them as 0-based for consistency with Tcl lists.

If supplied, keyIfAnyPtr is the name of a variable which will be set to the keyword of the specified descriptor record if theAEDescList is an AERecord or '****' otherwise.

If inPlace is true (default false), the new AESubDesc replaces theAESubDesc and is returned with the same hash key.

tclAE::subdesc::getNthData

Convenience access to data of AEGetNthSubDesc.

SYNOPSIS

tclAE::subdesc::getNthData <theAESubDesc> <theAEKeyword>

RESULT

Text representation of theAESubDesc key item.

DESCRIPTION

The descriptor record at position index is obtained from theAEDescList belonging to theAESubDesc. The resulting AEDesc is processed as by tclAE::desc::getData.

In the ToolBox, AEDescLists are 1-based, but TclÆ treats them as 0-based for consistency with Tcl lists.

If supplied, keyIfAnyPtr is the name of a variable which will be set to the keyword of the specified descriptor record if theAEDescList is an AERecord or '****' otherwise.

tclAE::subdesc::getType

Tcl wrapper for AEGizmos AEGetSubDescType call.

SYNOPSIS

tclAE::subdesc::getType <theAESubDesc>

RESULT

Descriptor type of theAESubDesc.

DESCRIPTION

This returns the descriptor type code of the sub-descriptor.

tclAE::subdesc::isListOrRecord

Tcl wrapper for AEGizmos AESubDescIsListOrRecord call.

SYNOPSIS

tclAE::subdesc::isListOrRecord <theAESubDesc>

RESULT

True if basic type of theAESubDesc is 'list' or 'reco'.

tclAE::subdesc::listSubDescriptors

List the active AESubDesc hash keys.

SYNOPSIS

tclAE::subdesc::listSubDescriptors

RESULT

List of AESubDesc hash keys.

DESCRIPTION

The hash keys for the active AESubDescs are compiled and returned in a Tcl list.

tclAE::subdesc::toDesc

Tcl wrapper for AEGizmos AESubDescToDesc call.

SYNOPSIS

tclAE::subdesc::toDesc <theAESubDesc> ¿desiredType?

RESULT

Hash key for new AEDesc.

DESCRIPTION

Copies a sub-descriptor into a brand new AEDesc. The resulting descriptor will be coerced to the desired type; if you don't want any coercion, use '****' as the desired type.

namespace tclAE::build

tclAE::build::event

SYNOPSIS

DESCRIPTION

tclAE::build::result

SYNOPSIS

DESCRIPTION

tclAE::build::List

SYNOPSIS

DESCRIPTION

tclAE::build::hexd

tclAE::build::bool

tclAE::build::long

tclAE::build::TEXT

tclAE::build::alis

tclAE::build::fss

tclAE::build::enum

SYNOPSIS

DESCRIPTION

tclAE::build::startupDisk

SYNOPSIS

DESCRIPTION

tclAE::build::throw

SYNOPSIS

DESCRIPTION

tclAE::build::username

SYNOPSIS

DESCRIPTION