Handling AppleEvents and coercions

- Handling AppleEvent Descriptor Coercions
  - tclAE::installCoercionHandler
  - tclAE::getCoercionHandler
  - tclAE::removeCoercionHandler
- Handling AppleEvents
  - tclAE::installEventHandler
  - tclAE::getEventHandler
  - tclAE::removeEventHandler

This page describes TclÆ calls for handling received AppleEvents and AppleEvent descriptor type coercion requests. For information on the associated ToolBox calls and data types, see INSIDE MACINTOSH: Interapplication Communication.

# Handling AppleEvent Descriptor Coercions

## `tclAE::installCoercionHandler`

Tcl wrapper for ToolBox AEInstallCoercionHandler call.

### Synopsis

`tclAE::installCoercionHandler fromType toType coercionHandlerProc`

### Result

None.

### Description

This call allows Tcl procs to act as `AEDesc` coercion handlers.

## `tclAE::getCoercionHandler`

Tcl wrapper for ToolBox `AEGetCoercionHandler` call.

### Synopsis

`tclAE::getCoercionHandler fromType toType`

### Result

Name of Tcl coercion `proc`.

### Description

The TclÆ coercion hash table is searched for the `proc` mapped by `fromType` and `toType`.

If the AEM has a registered coercion handler that is not a Tcl `proc`, the Result will be empty, but no error is thrown. Tell me how you want this to work!!!

Throws `OSErr -1717` (`errAEHandlerNotFound`) if there is no entry in the coercion hash table.

## `tclAE::removeCoercionHandler`

Tcl wrapper for ToolBox `AERemoveCoercionHandler` call.

### Synopsis

`tclAE::getCoercionHandler fromType toType coercionHandlerProc`

### Result

None.

### Description

The TclÆ coercion hash table is searched for the `proc` mapped by `fromType` and `toType` and matched with `coercionHandlerProc`. Although the `fromType` and `toType` parameters would be sufficient to identify the handler to be removed, providing the `coercionHandlerProc` parameter is a safeguard to ensure that you remove the correct handler.

Throws `OSErr -1717` (`errAEHandlerNotFound`) if there is no matching entry in the TclÆÕs coercion hash table.

# Handling AppleEvents

## `tclAE::installEventHandler`

Tcl wrapper for ToolBox `AEInstallEventHandler` call.

### Synopsis

`tclAE::installEventHandler aeclass aeeventID eventHandlerProc`

### Result

None.

### Description

This call allows a Tcl `proc` to act as an AppleEvent handler.

## `tclAE::getEventHandler`

Tcl wrapper for ToolBox `AEGetEventHandler` call.

### Synopsis

`tclAE::getEventHandler aeclass aeeventID`

### Result

Name of Tcl AppleEvent handler `proc`.

### Description

The TclÆ event handler hash table is searched for the `proc` mapped by `aeclass` and `aeeventID`.

If the AEM has an event handler that is not a Tcl `proc`, the Result will be empty, but no error is thrown. Tell me how you want this to work!!!

Throws `OSErr -1717` (`errAEHandlerNotFound`) if there is no entry in the event handler hash table.

## `tclAE::removeEventHandler`

Tcl wrapper for ToolBox AEGetEventHandler call.

### Synopsis

`tclAE::getCoercionHandler aeclass aeeventID eventHandlerProc`

### Result

None.

### Description

The TclÆ event handler hash table is searched for the `proc` mapped by this `aeclass` and `aeeventID` and matched with `eventHandlerProc`. Although the `aeclass` and `aeeventID` parameters would be sufficient to identify the handler to be removed, providing the `eventHandlerProc` parameter is a safeguard to ensure that you remove the correct handler.

Throws `OSErr -1717` (`errAEHandlerNotFound`) if there is no matching entry in the coercion hash table.

Copyright © 1999Ð2003 Jonathan E. Guyer
All rights reserved.

Last modified Saturday, November 29, 2003 02:38:18 PM