ACS ALOE suite


With ACS and MacApp ALOE framework classes, developers can get automatic OpenDoc embedding support into existing C++ applications. This document outlines the features, requirements, class design, and recipes for using the ACS and MacApp ALOE support. This document also provides alerts, milestones, and known problems indicated in red.

The goal for ACS ALOE support is to provide sufficient functionality in ACS to implement C++ framework ALOE support with the smallest impact possible on the framework itself, that can therefore be leveraged for any framework a developer chooses to use or implement themselves.

The design for these layers is driven by the features provided in ALOE that are appropriate for a robust framework such as MacApp, and by additional desired features that meet developer needs.


Features

ALOE is Apple's new OpenDoc container technology. ALOE does not require any special knowledge of OpenDoc API's or architecture. ALOE manages almost all of the interactions between your application and OpenDoc.

A summary of ALOE features useful for a container application include:

Additional ACS ALOE framework support includes:


Requirements

ALOE needs the ALOE shared library, OpenDoc 1.2 or later, and MacOS System 7.5 or newer to fully operate. The ALOE shared library must be installed in the OpenDoc Libraries folder located inside the Extensions folder of the active System Folder. In addition, an ALOE static library and resource files must be statically linked with each application that uses ALOE. ALOE provides static libraries for CodeWarrior 68K, CodeWarrior PPC, SCpp (68K), and MrC (PPC). 68K applications that use ALOE must be built using the CFM-68K model.

If an application using ALOE is run on a computer with an older version of OpenDoc or MacOS, or on a computer that does not have the ALOE shared library or OpenDoc installed, the ALOE-enabled application will still run, but any embedded objects will display as static images and cannot be activated or edited. 68K applications that use ALOE will not run on a 68K machine without the CFM-68K extension.


ACS ALOE class design

The ACS ALOE classes provide a very thin layer above ALOE. These classes C++-ize ALOE, without adding any performance or space penalties by inlining most calls directly to ALOE. C++ features include organizing subsets of the ALOE API around its conceptual components as classes, throwing a native C++ exception if an ALOE call returns an error, providing constructors, and so on. In a few places, programmer errors in the use of ALOE are detected and reported (when qCoreDebug is turned on). The most significant parts of ACS ALOE classes are where default ALOE functionality can be provided, such as OpenDoc event handling, adaptor selection, and focus management.

CODSession

Wraps global ALOE calls, provides default event handling behavior, OpenDoc focus management, and provides factory methods for creating AdaptorMgrs.

CODAdaptorMgr

Corresponds to a document, and encapsulates the root proxy part. Wraps AdaptorMgr calls, implements adaptor selection, and provides factory methods for creating Adaptors and AdaptorViews.

CODAdaptor

Corresponds to an embedded OpenDoc part and a single frame. Wraps Adaptor calls, a copy constructor and "synchronized adaptor" constructor (e.g., same part, new frame), and provides factory methods for creating AdaptorViews.

CODAdaptorView

Wraps AdaptorView calls, which correspond to an OpenDoc facet.

CODClipboardPromise

Implements the recipe for providing a clipboard promise to OpenDoc.


MacApp class design

Several classes extend the Sprokets classes to plug them into the MacApp architecture, while other classes extend MacApp to call the ACS ALOE classes.

TODSession

Subclass of CODSession that provides ALOE with MacApp's menu bar and registers OpenDoc CommandIDs for MacApp menus.

TODAdaptorViewProxy

A convenience class that allows for deferred instantiation of ALOE AdaptorView, since MacApp separates file reading from view creation.

TODPartView

Subclass of TView that exploits regions and presents a SODAdaptorView in the MacApp view system.

TODDispatcher

Subclass of TDispatcher, conditionally the base class for TApplication or TVUApplication if qALOE is turned on.

MODAdaptable

A lightweight mixin class that has an AdaptorMgr data member, which can be be mixed in to the appropriate context (document or window) of an application.

TODFileBasedDocument

A convenience document subclass that mixes in MODAdaptable with TFileBasedDocument and implements reading and saving Adaptors and view information.


Using ALOE in MacApp

To start using ALOE in your MacApp application, you must first turn on the ALOE support option in the MABuild tool, and rebuild the MacApp libraries so that the MacApp framework library is ALOE-aware.

In your project, add the AC_ALOELib corresponding to your compiler and debug setting (PPC or 68K, d or nd). No special initialization is required, because the qALOE option turns on support in the MacApp framework for automatically initializing ALOE support by default. TApplication will automatically descend from TODDispacther when qALOE is true.

Any document subclasses you create that need to store OpenDoc content *** even non-persistent content - a design change is pending to require this only for persistent content *** should be changed to derive from TODFileBasedDocument. Any document subclasses that don't store OpenDoc content can still be used in your application without subclassing from TODFileBasedDocument.

Where subclassing from TODFileBasedDocument is not possible or desirable, the MODAdaptable mixin class may be added for a document or window context in the application where OpenDoc content is used or permitted.

[*** Recipe for using MODAdaptable, from "Calc and Graph" TCalcDocument]

For applications that wish to provide OpenDoc support as an option without automatically starting up the ALOE session at MacApp startup time, your application subclass must override the StartSessionOnRun() method and call AC_CODSession::Instance()->Connect() when it needs to begin interacting with ALOE.

[*** Recipe for delayed OpenDoc session connection, from "Calc and Graph" TCalcApplication]


Using ACS ALOE classes

Generally, you will not directly interact with the ACS ALOE classes except to extend ALOE support, or to add ALOE support to another C++ framework. The single exception is that any developer implementing container support is likely to use the factory methods for creating an adaptor and adaptor view, and the methods for storing adaptor references and instantiating adaptors from storage.

[*** Recipe for creating adaptor and adaptor view, from "Simple Container" TDocumentSimpleContainer]

[***Recipe for storing and instantiating from storage from "Simple Container" TDocumentSimpleContainer]


Notes on changes to MacApp framework

There are several required changes to MacApp to conditionally support ALOE in order to minimize changes to existing MacApp applications.

UWindow.cp adds calls to ALOE, if conditionally compiled with qALOE, to guarantee that ALOE floating windows operate correctly when ALOE is present. *** An ACS base class for CWindow might help create an abstraction for ALOE window dependencies ***

UApplication.h and .cp conditionally subclasses TApplication from TODDispatcher and call the TODDispatcher constructor when qALOE is turned on, which creates a link-time dependency on UODDispatcher.cp and ACS ALOE source files.

TClipboardMgr depends on a ACS CClipboard class that encapsulates the scrap manager, that uses ALOE calls when qALOE is turned on. MacApp's TClipboardMgr creates this clipboard object.

AppleEvent Object dispatcher install and token resolution functions use ACS wrapper functions that use ALOE calls when qALOE is turned on.


Milestones

Blue with "/D" indicates the milestone has been reached; Red indicates a problem with ALOE or OpenDoc is preventing this milestone from being completed.

  1. /D Initialize and terminate ALOE
  2. /D Associate an AdaptorMgr with a new TFileBasedDocument
  3. /D Migrate ODPartView and sample code to new sample
  4. /D Set callbacks for window activation
  5. /D Create an AdaptorView from ISOString
  6. /D Create an AdaptorView from Drag
  7. /D Implement selection and activation
  8. (TODDocument) Save and open a document with an AdaptorMgr
  9. Add show/hide and bundle etc. state support to ODPartView
  10. Support Undo/Redo
  11. /D Support Clipboard operations
  12. /D Add basic scripting support
  13. /D Implement an Adaptor example (Calc)


Known problems

[1603422] ALOE's automatic MacApp CMNU command registration is gives errors, and could not be used, so regular MENU resources must be swapped in and out.

[1603429] Window activation (SelectWindow) is not working correctly when AdaptorViews have been added to windows. Switching in and out of the application re-synchronizes the active window.

??? [ALOE/MacApp] Menus don't appear for the active adaptor view unless the adaptor adds menus or changes the state of the File or Edit menu items. When menus do appear, they are usually appropriate for the part, but the File and Edit menu items sometimes are left enabled by a previously active adaptor that another adaptor can't handle.

??? [ALOE/MacApp] Clicking on my floating window title bar beeps when an ALOE adaptor has the focus. Should the app hide its floating windows when an ALOE adaptor is active?

??? [MacApp Occasionally get an unmapped memory exception on quitting, not reproduced yet.

??? [MacApp] Following the TESample example for calling ApplicationActive in response to an activate event deselects the current adaptor when switching windows or closing dialogs. Is this desired behavior?

??? [ALOE] Drag and drop two stationery documents, it embeds the first one twice.

Last updated: 02/19/97