Tk-Components

NAME
aem

SYNOPSIS

package require aem

aem::installeventhandler eventClass eventID command

DESCRIPTION

This package provides a lightweight mechanism for Tcl/Tk applications on Mac OS X to respond to Apple Events, the Mac's system-level application IPC protocol. The Apple Events mechanism allows Mac applications to script other applications using the AppleScript language--to query them for data, execute commands, and similar functions--in a manner similar to COM scripting on Windows and shell scripting on Unix. The package differs from an older Apple Events package, TclAE (http://tclae.sourceforge.net/), which is a thin wrapper over tne entire Apple Event framework and is more low-level and complex. The aem package only provides a way for a Tcl application to respond to Apple Event queries sent to it by other processes, i.e. to make a Tcl application scriptable via AppleScript. 

The aem package defines only a single command, aem::installeventhandler, which takes three parameters: an event class, an event ID, and a Tcl command. The event class and event ID are arbitrary four-character codes that are registered with the operating system via the installeventhandler command, and the Tcl command is the internal Tcl command that is executed when the application receives an Apple Event. Conceptually, the event class can be viewed as the application or developer's signature, while the event ID corresponds to specific commands it may execute. 

This module is designed to be easy to call from other scripting languages that have bindings to Tk, such as Python, Perl, and Ruby; all three langauges have mechanisms that allow functions in those lanaguages to map to Tcl commands, which would allow them to execute code in response to Apple Events as well.

In-depth discussion of the Apple Events mechanism and how to register an application to support Apple Events is outside the scope of this documentation, but these reference materials may be helpful: 

Detailed documentaton of the Apple Event framework, with a good overview of the basics at the beginning: 
https://developer.apple.com/legacy/library/documentation/AppleScript/Conceptual/AppleEvents/AppleEvents.pdf

Documentation on creating a scripting definition (SDEF) file, which is an XML file that lists the Apple Events the application supports: https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_creating_sdef/SAppsCreateSdef.html

A simple GUI tool for create SDEF files: http://www.shadowlab.org/softwares/sdefeditor.php


EXAMPLES

The following command registers an application to respond to an Apple Event. The application signature, or event class, is "coKV"; the event ID is "hihi"; and the Tcl command is "hello." 

aem::installeventhandler coKv hihi hello

An external application can call the Tcl application with this AppleScript code: 

tell application "MyTclApp"
	hello
end tell

This code will in turn cause the Tcl application to execute the following procedure:

proc hello {} {

return "hello from MyTclApp\n"

}

KEYWORDS

AppleScript, Apple Events, Mac

    /*Need to convert paramstring to something Tcl can handle gracefully. Direct conversion of AE params to char does not seem to work well, produces garbage.*/

    CFStringRef arg = CFStringCreateWithBytes(0, paramstring, sizeof(paramstring), kCFStringEncodingUTF8, false);
    CFDataRef data;
    data = CFStringCreateExternalRepresentation(NULL, arg, kCFStringEncodingUTF8, 0);
    if (data) {
      as_arg = (const char *)CFDataGetBytePtr(data);
      fprintf(stdout, "The parameter is %s", as_arg);
    }
    CFRelease(arg);
  } else {
    as_arg  = " ";
  }
   
  /*  Get command keyed to eventID from dict and pass to Tcl for execution. */