EGO (Edit Graphic Object) specification

EGO (Edit Graphic Object) is a Mac protocol that employs Apple Events to implement editing of graphical objects (e.g. equations) embedded in an application's documents. It is similar to the object embedding features of Microsoft’s OLE but EGO is much simpler to implement and more broadly supported among Mac applications. This document gives a Mac programmer the information needed to add EGO support to their application. It also contains details regarding the EGO support in MathType.

An EGO object is typically a graphic, e.g. a picture, equation or chart and is created by an application with EGO server support. When the user double-clicks on an embedded object, a window opens containing the object, ready for editing. When the user has finished editing the object and closes its window, the new version of the object replaces the original in the document. This is a much easier process than using Cut and Paste, and gives the user the feeling that the two applications are integrated.

The EGO protocol describes the process of transferring the object from the document's application (the client) to the object’s application (the server), and also returning the edited object back to the client. For EGO to work, both the client and the server must adhere to the conventions outlined in this document.

EGO relies on Apple Events for inter-application communication. The EGO protocol consists of three Apple Events, two of which are defined in Apple’s Apple Event Registry. These two events (EditGraphic and SetData) are extended beyond their original definitions by the use of additional optional parameters. The third event, ComeHome, is a completely new event.

Since OS X 10.4, PICT has been a deprecated image format. Version 2 of the EGO specification introduced support for PDF, and version 3 introduces support for MathML and LaTeX. This takes the form of new parameters for sending and requesting data in a specific format, and for requesting a graphic in a new format without opening the old object in a window for editing to facilitate batch conversions of EGO objects in the deprecated PICT format.

Since PICT is deprecated, EGO clients are encouraged to prefer the PDF format whenever possible, subject to backward compatibility considerations, and to keep in mind that future versions of EGO servers will likely drop support for PICT entirely at some point.

EGO, like OLE, is really an automated alternative to cut and paste between separate applications. With EGO, once an object has been embedded (using a Paste command) all further editing can be accomplished without using the Cut and Paste commands. The smoothness of the operations creates the impression of using an integrated application, and allows users to focus on what they're trying to accomplish, rather than the mechanics of the process.

EGO is different from Publish and Subscribe in that the EGO object is embedded directly into a document, rather than residing in a separate file. For documents that contain many embedded objects (e.g. a technical paper may contain hundreds of equations), this is a huge advantage. In addition, editing an EGO object requires fewer steps for the user.

OLE's embedded objects feature is Microsoft’s solution to the same problem that EGO addresses. It is a standard in the Windows environment, but so far has only been implemented on the Mac by Microsoft’s Word, Excel and PowerPoint products, as well as MathType OLE also uses Apple Events, but it is a more complicated protocol, and is harder for developers to implement than EGO. However, it does support a couple of features that EGO does not, namely the ability to use an Insert Object command to select an object-type from a list and open its editing window. By contrast, all EGO objects must be initially inserted into a document using a Paste command (see the section entitled "MathType's extension to EGO" below, for an extension that enables an Insert Object command to be supported). EGO and OLE support are not mutually exclusive MathType is an OLE and an EGO server), but most client applications will choose to support only one.

An EGO object is a PDF or PICT graphic that contains the EGO picture data (stored a comment in PICT files and as a private dictionary in PDF files). This data contains information that allows EGO clients to know which application created the object, as well as its size and other positioning information. When the user pastes a graphic into an EGO client, the client searches for the EGO data. If it finds EGO data, the client has to remember that this graphic is an EGO object. When the user double-clicks on the graphic, the client will create an EditGraphic Apple Event that contains a copy of the graphic, and send it to the graphic’s creating application (as indicated in the graphic’s EGO data). If the application isn’t running, the client will launch it and then send it the EditGraphic event.

Version 3 of the EGO specification introduces the capability for a client to send MathML or LaTeX equation data not embedded in a graphic object directly to the EGO server to obtain the corresponding graphic in return.

When the server receives the EditGraphic event, it opens a new window containing the object to be edited, and sets the title to something like “Equation from DocMaster” (the client’s name is one of the event parameters). After editing, the user closes the window and the server sends a SetData event back to the client, containing the new version of the graphic. For situations where a client wishes to convert between equation formats, the client can suppress the opening of the MathType UI and immediately obtain a graphic in response, via the use of the optional Rfsh keyword in the EditGraphic Apple event.

The client then inserts the graphic in the correct location within the document and becomes the front-most window, ready for further editing.

If the client requires the current version of the object while its EGO window is still open (e.g. the user closes the client document),  the client sends a ComeHome event to the server, instructing it to return the latest version of the graphic. All returned EGO objects are then inserted into the document before it is closed.

A fairly simple extension to the EGO specification allows a client application to support, for example, an Insert Equation command. This command is virtually essential when working with objects, as it allows users to edit and create objects without manually switching applications.

If MathType receives an EGO message without a 'data' parameter it will open an empty equation window, giving the user the idea that they’re creating a new equation. To support this functionality, the client application must know the application signature of the objects it wants to be able to insert (remember, when editing a graphic this signature is retrieved from the graphic itself).

Although this extension is not part of the official EGO specification, we suspect that most other EGO servers act in a similar way.

This section consists of two source file listings: a prototype and implementation of the function 'LaunchByCreator' which illustrates the launching requirements discussed in Launching an EGO Session above.

File 1: LaunchByCreator.h

// LaunchByCreator.h --- © 2018, WIRIS Europe (Maths for more S.L), All rights reserved.
// Purpose: Routine to launch app (typically MathType or Equation Editor) by creator code

// Note all types are standard Apple types.

// Launch app (typically MathType) by creator code.
// Uses Launch Services to find application, Process Manager to launch.
// Suppresses sending Open Application %%('%%oapp') Apple Event to app on launch by default.
// Skips launch if application is already running but bring to front.

OSStatus // toolbox error code if error, noErr otherwise
LaunchByCreator(
    OSType inCreator,               // Creator code for app to launch
    bool suppressOAPP = true,       // Suppress Open Application 'oapp' event
    AppParametersPtr firstEvent = 0 // First event delivered to app, 0: use null event
                                    // (ignored if suppressOAPP is false)
);> );

File 2: LaunchByCreator.cpp

// LaunchByCreator.cpp --- © 2018, WIRIS Europe (Maths for more S.L), All rights reserved.
// Purpose: Routine to launch app (typically MathType) by creator code

// Note all types are standard Apple types.

#include <Carbon.h>
#include "LaunchByCreator.h"

// Find running app by signature and return PSN
static bool
FindRunningAppBySignature(
    OSType signature,
    ProcessSerialNumber &psn
){
    ProcessInfoRec info;  // Process Information Block
    info.processInfoLength = sizeof(info);
    info.processName       = 0;
    info.processAppSpec    = 0;
   
    psn.highLongOfPSN = 0;
    psn.lowLongOfPSN  = kNoProcess;

    // search running processes for an app with our signature...
    while( (::GetNextProcess(&psn) == noErr) && (::GetProcessInformation(&psn, &info) == noErr) ) {
        if( (info.processType == 'APPL') && (info.processSignature == signature) ) {
            psn.highLongOfPSN = info.processNumber.highLongOfPSN;
            psn.lowLongOfPSN = info.processNumber.lowLongOfPSN;
            return true;
        }
    }
    return false;
}

// Launch app (typically MathType) by creator code.
// Uses Launch Services to find application, Process Manager to launch.
// Suppresses sending Open Application ('oapp') Apple Event to app on launch by default.
// Skips launch if application is already running but bring to front.

OSStatus // toolbox error code if error, noErr otherwise
LaunchByCreator(
    OSType inCreator,                         // creator code for app to launch
    bool suppressOAPP           /* = true */, // suppress Open Application 'oapp' event
    AppParametersPtr firstEvent /* = 0 */     // first event delivered to app, 0: use null event
                                              // (ignored if suppressOAPP is false)
){
    ProcessSerialNumber psn;
    if( FindRunningAppBySignature(inCreator, psn) ) {
        return ::SetFrontProcess(&psn);
    }

    OSType inType = 'APPL';
    CFStringRef inExtension = CFSTR(".app"); // can be NULL
    LSRolesMask inRoleMask = kLSRolesAll;
    FSRef outAppRef; // can be NULL
    CFURLRef * outAppURL = 0; // can be NULL

    // Obtain file system reference for application with given creator
    OSStatus status = ::LSGetApplicationForInfo( inType, inCreator, inExtension,
                                                    inRoleMask, &outAppRef, outAppURL);
    if( status != noErr )
        return status;

    // Convert FSRef returned by Launch Services into FSSpec required by LaunchApplication
    FSSpec spec;
    OSErr err = ::FSGetCatalogInfo(&outAppRef, kFSCatInfoNone, NULL, NULL, &spec, NULL);

    if( err != noErr )
        return err;

    // Null event to suppress Open Application Apple Event if not supplied as argument
    AppParameters appParams;
    appParams.theMsgEvent.what = nullEvent;
    appParams.theMsgEvent.message = 0;
    appParams.theMsgEvent.when = 0;
    appParams.theMsgEvent.where.v = 0;
    appParams.theMsgEvent.where.h = 0;
    appParams.theMsgEvent.modifiers = 0;
    appParams.eventRefCon = 0;
    appParams.messageLength = 0;

    // Choose first event pointer
    AppParametersPtr appParamsPtr = 0;
    if( suppressOAPP ) {
        if( firstEvent != 0 )
            appParamsPtr = firstEvent; // use supplied event, if any
        else
            appParamsPtr = &appParams; // otherwise use null event
    }

    // Configure parameter block
    LaunchParamBlockRec launchParams;
    launchParams.launchBlockID = extendedBlock;
    launchParams.launchEPBLength = extendedBlockLen;
    launchParams.launchFileFlags = launchNoFileFlags;
    launchParams.launchAppSpec = &spec;
    launchParams.launchControlFlags = 0;
    launchParams.launchAppParameters = appParamsPtr;

    err = ::LaunchApplication(&launchParams);

    return err;
}
  |