ODB Editor Suite

Introduction and Important Notes

This document describes an Apple Event-based interface that developers may take advantage of in order to provide better integration between their products and BBEdit. Although the interface is not a full-blown external editor interface of the sort originally supported by the Symantec and Metrowerks (and now Xcode) IDEs, it is easy to implement and support.

It is important to note that this is not a generalized external-editor interface; there is no provision for arbitrating for a window’s text, for example (although the server application could use BBEdit’s existing Apple Event interface for this purpose).

Note to text editor authors: if you want to implement the editor side of the ODB editor suite in your product, go right ahead. However, be advised that the specification is subject to change without notice as may be necessary to meet the needs of third-party developers. In addition, this document may not be excerpted or reproduced (except for the purposes of making a backup copy), and any derivatives of this suite must be clearly labeled as such.

For that reason, if there is a modification or enhancement to this suite that you need to make, please let us know so that we can incorporate it into the reference implementation (or suggest an alternate approach if not). Any reasonable proposal will be considered.

Following these guidelines will ensure the broadest possible adoption of the ODB Editor Suite, and the best possible experience for the user.

This document assumes a reasonable level of familiarity with the Mac OS programming API, including the Process Manager and the Apple Event Manager. The symbolic names of constants in the ODB Editor Suite are defined in the header file “ODBEditorSuite.h”, included in the SDK. (Download the SDK.)

Opening Documents

The interface is based on a simple operating model: The “server” (that is, the application that wishes to have BBEdit edit its text files), sends the “open document” (kCoreEventClass/kAEOpenDocuments) event to BBEdit. When doing so, the server adds an additional parameter to the ‘odoc’ event. BBEdit uses this pararameter to notify the server when the user has saved or closed the file in question, so that the server may update internal state, re-process the file, and so on.

When the server wishes to be informed upon saving or closing of a specific document, the server application should attach a parameter to the ‘odoc’ event that it sends to BBEdit:

parameter keyword:	keyServerID
parameter type:	typeType

The keyServerID parameter is an OSType (that is, a four-byte character constant) which is the application signature of the process to be notified when the user saves or closes the document specified in the ‘odoc’ event.

In addition to the keyServerID parameter, the server may attach additional information about the documents being opened. The following parameters are optional:

Keyword	Type
keyFileSenderToken	typeWildCard
keyFileCustomPath	typeUnicodeText (typeChar supported but deprecated)

If the keyFileSenderToken parameter is present, the data contained in it will be attached to the document, and sent back to the server application with a close or save notification (see below). BBEdit does not inspect or interpret the data in this parameter; it can contain anything.

If the keyFileCustomPath parameter is present and is (or can be coerced to) typeUnicodeText, then the character data is displayed in the editing window’s status bar, in preference to the actual file path. An example of this usage is for an FTP client: rather than seeing the local file path, the user would rather see the FTP path; if you supply the FTP path in a keyFileCustomPath parameter, they will.

Notifications

Having informed BBEdit that it wishes to be notified, the server application should be prepared to receive the following Apple Events:

File Modified

event class:	kODBEditorSuite
event ID:	kAEModifiedFile

parameters:

keyword:	keyDirectObject
type:	typeFileURL (may also use typeBookmarkData. typeFSRef supported but deprecated)
meaning:	the file being modified

keyword:	keyNewLocation
type:	typeFileURL (may also use typeBookmarkData. typeFSRef supported but deprecated)
meaning:	if the file is being saved to a new location (as in Save As), this parameter contains the file system location of the new copy.

keyword:	keySenderToken
type:	typeWildCard
meaning:	if the server passed a token for this file (see keyFileSenderToken, above), then the token for the file being saved is included in the event.

BBEdit will send the kAEModifiedFile event to the server whenever the user chooses “Save” or “Save As…”. The keyDirectObject parameter contains the file system location of the file that is being saved. The keyNewLocation parameter is optional; if present, then the file is being saved to a new location (probably via Save As…). If the server specified a file-specific parameter when asking BBEdit to open the file, then that parameter data is included as the keySenderToken parameter.

File Closed

event class:	kODBEditorSuite
event ID:	kAEClosedFile

parameters:

keyword:	keyDirectObject
type:	typeFileURL (may also use typeBookmarkData. typeFSRef supported but deprecated)
meaning:	the file being closed

keyword:	keySenderToken
type:	typeWildCard
meaning:	if the server passed a token for this file (see keyFileSenderToken, above), then the token for the file being saved is included in the event.

BBEdit will send the kAEClosedFile event to the server whenever the user closes the document (either directly, via the “Close” command, or indirectly, by quitting BBEdit). The keyDirectObject parameter contains the file system location of the file that is being closed. If the server specified a file-specific parameter when asking BBEdit to open the file, then that parameter data is included as the keySenderToken parameter.