This document is outlines the SerialMagic engine API interface on OS X.

On OS X, the SerialMagic API is provided via AppleEvents sent using AppleScript. AppleEvents were choosen for the SerialMagic API due to the flexibility of AppleScript and AppleEvents.

SerialMagic and AppleScript

AppleScript has been a part of the Mac OS as far back as System 7 in 1993. AppleScripts are commonly created using Apple's Script Editor. AppleScripts can coordinate the actions of normally unconnected applications, making data from one application available to another.

An AppleScript sends AppleEvents. Applications created using Apple's Cocoa framework have a core of understanding for AppleEvents that handle common actions like cut, copy and paste. But every application is free to create specific AppleEvents handlers for actions that serve its own purposes.

SerialMagic normally sends keystrokes to any application. Most applications have some way of processing keystrokes and SerialMagic can send data to these application by this method.

SerialMagic also offers the option of sending data to another application as an AppleEvent. These AppleEvents are sent directly from the SerialMagic application, without the need for an AppleScript.

However, unlike the common actions of cut, copy, and paste, no application will understand the AppleEvent sent by SerialMagic without preparation. While the data is sent from SerialMagic as text, the application receiving it needs to specifically declare that it can accept the data.

The "AE Sample" Xcode Cocoa project demonstrates a way of creating an application, named ScanViewer, which understands the SerialMagic AppleEvent. To use the terminology of AppleScripting, the ScanViewer application has a dictionary with an entry for the SerialMagic AppleEvent.

When the SerialMagic application is sending AppleEvents, it checks the target application's dictionary to see if it has an entry for the SerialMagic AppleEvent. If no entry is present, then no AppleEvent is sent. Any application which needs to receive the SerialMagic AppleEvent should follow the example of the ScanViewer sample project to create the proper dictionary entry.

The AppleEvent dictionary entry must contain the following information.

• It must have a section named "SerialMagic Suite".
• The SerialMagic suite must have a class name entry for "application" with the Apple-specified code of "capp".
• The code value of the entry must be "flic", and the type must be "text"
• To follow the example of the AE Sample project, the Cocoa applications should have a cocoa key, named "scanText".

The last item, the cocoa key, determines the name of the method used to handle the AppleEvent. After receiving the AppleEvent, the application is free to use the data in any way it chooses, but in order to receive the data, it must use a properly named method.

By convention, the method names called by the Cocoa AppleEvent handler are derived from the cocoa key value in the AppleEvents dictionary. In the "AE Sample" Xcode Cocoa project, the cocoa key value is "scanText" so the method name for receiving the data must be "setScanText".

All of this and more can be seen in the "AE Sample" Xcode Cocoa project. This example project is ready to compile, and builds an application named ScanViewer. ScanViewer will receive and display AppleEvents sent from SerialMagic. After studying the AE Sample project and ScanViewer, you will be ready to include AppleEvent handling for the SerialMagic AppleEvent in your own application.

Download the SerialMagic API example Xcode Cocoa project.