The ODB Editor Suite is an AppleEvent-based protocol published by BareBones Software. It allows for a Mac OS X application to request that another application edit a file, and report back when that file is modified or closed.

The documentation provided with the SDK does a good job explaining how a “Server” application (an application that needs some editing done) can send and receive the appropriate AppleEvents to an editor like BBEdit. Many third party applications now support the client side, but the “how to” is not documented very well. For those not intimately familiar with AppleEvents, getting started can be a bit daunting. This article, and the provided sample applications, aim to fill in that knowledge gap.

Sample Source

The sample zip for this article contains:
LilPad – A small text editor application, which implements the client side of the ODB Editor Suite.
ODBServer – A testbed application which can be used to invoke ODB client applications.
ODBSuite – A directory containing a stub for the ODBEditorSuite.h header file. This must be downloaded directly from BareBones Software.

Handling the ‘Open File’ AppleEvent

Most document-based applications are already set up to handle this event. Even if you aren’t explicitly adding a handler for the kCoreEventClass/kAEOpenDocuments AppleEvent, the Cocoa frameworks are set up to handle this via your NSDocument class, or the NSApplicationDelegate application:openFiles: message. The LilPad sample application does this in the override of the readFromURL:ofType:error: message (in MyDocument.m).

The AppleEvent sent by an ODB Server app will contain the extra ‘FSnd’ (keyFileSender) parameter. The client application must save this identifier in order to properly respond to the server app. A server app will also usually send an identifying token (keyFileSenderToken, ‘FTok’) and a “Custom Path” (keyFileCustomPath, ‘Burl’), which is usually used to specify a more friendly display name, rather than the full file path. A client app can safely ignore the keyFileCustomPath parameter, but should retain the reference to the token if one is provided.

If you’re authoring an NSDocument-based application, you can store the associated parameters right in the document object. Otherwise, you’ll need to set up a dictionary to hold the parameter values.

Notifying the Server

The code that demonstrates notifying the server application is found in the LilPad sample, in MyDocument.m. The [MyDocument saveDocument:] and [MyDocument close] messages override the NSDocument base implementation in order to inform the server application that changes were made. [MyDocument setFileURL:] is overridden in order to handle the “Save As” operation.

The client application must do the following.

  • Construct an AppleEvent with the class code of kODBEditorSuite.
    The eventID is either kAEModifiedFile, kAEClosedFile, or keyNewLocation.
    keyNewLocation is used when the client application performs a “Save As” operation.
  • Identify the target of the AppleEvent by the server application’s package signature. This is the ‘FSnd’ value of the “Open Files” event.
  • The keyDirectObject of the event should be set to the “file://path/to/doc.txt”-style URL of the modified/closed/renamed file, with a descriptor type of typeFileURL.
  • If the original “Open Files” event specified a token, this should be sent back as the keySenderToken parameter. Simply provide the reference to the NSAppleEventDescriptor that was retained earlier from the keyFileSenderToken param.

Give it a spin

The ODBServer application can be used to test your ODB Client application. Simply replace the hard-coded reference to the LilPad bundle id (com.slickedit.lilpad) with that of your own application.