AEGizmo, AEBuildAppleEvent and Mac OS X 10.4

"AEGizmos" (or more often, simply "AEGizmo") is the name for a set of APIs developed by Apple’s Jens Peter Alfke between 1991 and 1995. He used to distribute the routines for free on his website and they became fairly popular. Apple Developer Technical Support officially "supported" the use of the API.

With Mac OS X the routines were tweaked and officially rolled into the operating system (and pulled from Jens’ site). The famous Technote 2045 describes the official API and how to use it. The incredibly powerful AEBuildAppleEvent API can be used to build a complex Apple Event with a stack of parameters using a single line call.

Unfortunately, working out the required "AEGizmo" string and getting the syntax right can be incredibly difficult. Apple provides no API for generating AEGizmo strings (although curiously it does provide a function, AEPrintDescToHandle, that produces output compatible with AEBuildDesc but not with AEBuildAppleEvent; why the two routines use different syntaxes is somewhat of a mystery).

You can use the AEDebugSends and AEDebugReceives enviroment variables to see pretty-printed information about incoming and outgoing Apple Events, but converting this information to AEGizmo format is a painstaking and error-prone process.

You could also use some gdb trickery as described here but you won’t get the results that Rosyna says you should:

core\getd{ ----:obj { form:'prop', want:'prop', seld:'pnam', from:'null'() }, &csig:65536 }

What you actually get is this (at least on Mac OS X 10.4 and 10.4.1; I don’t know about previous versions):

'core'\'getd'{ '----':'obj '{ 'form':'prop', 'want':'prop', 'seld':'pnam', 'from':''null''() }, &'csig':65536 }

Feed a string like that to AEBuildAppleEvent and you’ll get a syntax error. In some cases with strings like this you can correct the syntax errors but you may find that AEBuildAppleEvent doesn’t return the results you expect even if it does execute without returning any errors. The reason these strings are inadequate is that they’re generated by AEPrintDescToHandle, which is not intended to be used with AEBuildAppleEvent. The above example correctly formatted as a true AEGizmo string would look like this:

'----':obj {form:prop, want:type(prop), seld:type(pnam), from:'null'()}

Prior to Mac OS X 10.4, you could use an application called AE Monitor to watch Apple Events and convert them to AEGizmo strings. At the time of writing the current version (1.7.2) has not been updated to work on Tiger. I’m not a big fan of REALbasic; I found the app to be slow, klunky, and to deviate too far from well-established Mac user interface standards for my liking but at least the app worked. It was fairly buggy, it crashed a lot, it cost $40, but it did produce AEGizmo strings that worked.

Another option was and still is Script Debugger. Script Debugger has an Apple Event log window which shows the same output as that produced by the AEPrintDescToHandle function; in other words, output which is incompatible with AEBuildAppleEvent. If you launch Script Debugger in the Classic environment then it will fall back and use some older routines that it has based on the original AEGizmo code and it will produce output which in many cases does work with AEBuildAppleEvent. Nevertheless, you’ll still find cases where the strings don’t work with the new API, and the application itself costs $189; a hefty price tag if all you want to do is figure out the AEGizmo representation of a one-line AppleScript.

In the course of developing Synergy Advance I’ve had to work out a lot of AEGizmo strings. I’ve written my own application for converting AppleScripts to the AEGizmo string equivalents. The application provides a basic interface which is like a simplified version of Apple’s Script Editor. It supports syntax coloring, gives you a "Compile" and a "Run" button, and most importantly shows you the AEGizmo string representation of the script (and the reply, if there is one). If there is enough interest from developers, I’ll package it up and release it with a fairly low price tag.