TweetFollow Us on Twitter

Extend OpenDoc with SOM

Volume Number: 13 (1997)
Issue Number: 4
Column Tag: Programming Techniques

Using SOM to Extend Your OpenDoc Parts

by Gerry Kenner, University of Utah, David Kenner, Phone Directories, Deborah Grits, Apple Computer

An introduction to SOM and OpenDoc extensions with an overview of Apple's ScriptRunner sample code

With the release of OpenDoc, version 1 (DR4) in January 1996, Apple provided the developer community with a powerful tool for creating interchangeable software modules. The good news is that component parts for use inside of applications such as Microsoft Excel and ClarisWorks can be produced quickly using the tools provided. Further, the OpenDoc Frameworks Library (ODF) is definitely a step in the right direction - providing tools to take care of routine graphic interfacing.

Unfortunately, OpenDoc parts are optimized for responding to menu and user events and cannot easily communicate with each other directly. The problem is summarized on p.69 of the OpenDoc Programmer's Guide. "The basic architecture of OpenDoc is primarily geared toward mediating the geometric interrelationships among parts, their sharing of user events, and their sharing of storage. Direct communications among parts for other purposes than frame negotiation is mostly beyond the basic intention of OpenDoc. If separate parts in a document (or across documents) need to share information, or if one part needs to manipulate the contents or behavior of another part, you need to extend the capabilities of OpenDoc in some way."

Translated, this says that you cannot conveniently pass parameters to and from a part without adding extension subclasses. To do this, you must write and compile SOM idl files. Fortunately writing, modifying and compiling idl files is not difficult as we will show in this article.

In this article we approach the subject of OpenDoc extensions in the following way.

1. Explain what extensions are.

2. Provide a glossary of some of the common terms we will be using in this article.

3. Show how extensions work by providing a detailed description of Apple's ScriptRunner demo. This will also show how to use lists, shared resources and shell plug-ins.

4. Outline and build a simple example which will show how to write the necessary code for implementing a minimal extension.

5. Provide instructions for compiling the files by executing the SOM compiler from within Apple's MPW Shell program or the ToolServer.


What are these magic things called extensions? First, we consulted Chapter 10 of the OpenDoc Programmer's Guide and determined that OpenDoc uses the extension mechanism for the following:

• Expanding the object interface.

• Creating custom event types.

• Creating custom focus types.

• Supporting scripting.

• Customizing information returned by the Part Info dialog box.

Also, extensions can be used for graphical transformations, creating shell plug-ins and writing OpenDoc patches.

These things are possible because all subclasses of class ODObject can be extended using subclasses of the ODExtension class.

Extensions operate by providing an interface to a part which can be accessed by other parts. The extension has methods which when called will relay the call to the corresponding methods of the parent classes.

Figure 1 shows how this works for the ScriptRunner example.

Figure 1. The HandleMenuEvent method of the TextEditor object can access the Show method of the ScriptRunner object thru the PaletteExt object, which is a subclass of ODExtension.

Some OpenDoc Terminology

Here are some terms used in the material that follows:

Name space

Object (or list) which maps data types to values. If published, name spaces can be used globally.

Plug-in module

Shared libraries which must be installed when a document which has parts that use them is first opened. They modify or extend the functions of the document shell. They are not ODExtension subclasses.

Document shell or document shell program

Managing the environment of the parts in a document.


Mechanism for expanding the functionality of the OpenDoc classes.


Code for performing tasks such as instantiating an object.

ScriptRunner Project

Apple included a project in the version 1.0 release of OpenDoc (Developer Release 4) named ScriptRunner. The function of ScriptRunner was to demonstrate how to program and use extensions and plug-ins. ScriptRunner was designed to enhance the capabilities of another Apple Demo part, TextEdit, by adding a palette with scripting functions.

ScriptRunner has several components, an OSA plug-in, a data transfer extension, a scripting palette extension and the ScriptRunner part. The interrelationship between the components and the TextEdit part is shown in Figure 2.

Figure 2. Relationships of the various components of the ScriptRunner system. Modified from illustration in Apple's ScriptRunner Read Me document entitled "ScriptRunner Mechanics."

ScriptRunner operates as follows. The TextEdit part is opened and the user either types or pastes an Apple script into the active text window. The menu item "Show ScriptRunner" of the Tools menu is then selected (Figure 3). The ScriptRunner part is instantiated and the ScriptRunner palette appears in the document window. Selection of the Run item of the palette results in execution of the script contained in the text window. At the end of execution, a dialog box appears with the results returned by the AppleScript. It will read "No results" if nothing is returned. As of DR4, the record function had not been implemented.

Figure 3. Window of TextEditor at the completion of an execution cycle of the Run command of ScriptRunner.

Now that the reader understands how ScriptRunner is called and what it does, we will show the details of the operation. For clarity, we will present this in several segments.

OSA Plug-in

Plug-ins are shared libraries which are called by the document shell when a document is created. When a document is opened, the document shell is launched by OpenDoc. The document shell sets up the document after which it calls the install methods of associated plug-ins. Once this is done, the shell finishes setting up the document by opening its window.

Each shell plug-in has a single exported entry point, its install function. The OSA plug-in's install function is named ODShellPlugInInstall. This function creates a name space for storing an object reference to an object of the class ScriptRunnerAgent. It then instantiates the object and puts its address in the name space (Figure 4).

Figure 4. Creation of name space and ScriptRunnerAgent objects, followed by storage of an object reference to the ScriptRunnerAgent object in the name space object.

Accessing ScriptRunnerAgent by TextEdit

ScriptRunner is accessed by selecting the "Run ScriptRunner" item from the Tools menu. The first time this occurs, the program checks to see if ScriptRunner is available and then installs it (Figure 5). This is done by retrieving the reference to the ScriptRunnerAgent from the name space and using its methods to instantiate the ScriptRunner part.

Figure 5. Sequence of events following selection of "Open ScriptRunner" item of tools menu.

Accessing the palette extension

For a client part to use another part's extension, it calls the method AcquireExtension to get a reference to it. AcquireExtension will create a new extension object if one does not already exist

Using the palette extension

At this point, the palette menu is showing. Selection of the Run item results in the sequence of events shown in Figure 6.

Figure 6. Program flow when the Run item of the Palette is selected.

Extension Project

Planning Stage

We are going to design a simple project to demonstrate how to write an extension which has minimal functionality.

Business Sublevel

Our starting point is the Image project that was described in the February, 1996 issue of MacTech Magazine. This project involved the creation of objects of two parts named ImagePart and SelectPart. Following instantiation, the ImagePart object displayed a read only text screen and had a menu option for selecting the name of a text file. Selection of the menu option resulted in the instantiation of the SelectPart object which automatically displayed an SFGetFile dialog box that asked for a file name. The SelectPart object then placed the name in global storage from which it was retrieved by the ImagePart object. The name was then displayed in the read-only window.

Solution Sublevel

ImagePart will be simplified by having it call the MyOpenPict method from its InitializeFromStorage method thus bypassing the menu operations. This is bad practice but it does enable getting a program running quickly. The MyOpenPict method will instantiate a SelectPart object and call one its methods which was added via the extension mechanism.

The ODExtension subclass GetNameExt will add a method named GetName to SelectPart. The extension will be accessed by ImagePart which will then call the method. The method GetName will display a dialog box asking for the name of a file. This is to provide visual evidence that calling the method was successful.

To simplify our demo, we are not going to pass or return any parameters. Adding this functionality is moderately complicated and will make a good subject for a future article.

Prototyping Level

Figures 7 and 8 give the general layout for running the modified image program. After instantiating SelectPart, ImagePart will interrogate it to determine if it has the desired extension for getting a file name. If it is available, a call will be made to obtain the file name. The SelectPart object will then be disposed of and the ImagePart object will be displayed (Figure 7).

Figure 7. Outline of activities of the ImagePart part.

An overall outline of the operations of the SelectPart object is shown in Figure 8.

Figure 8. Outline of operations of SelectPart.

Flow Diagramming Level

Figure 9 shows the flow of the MyOpenPict method. The SelectPart part is instantiated followed by the acquisition of a pointer to the GetNameExt extension (AcquireExtension method). A call is then made to the GetName method of the extension. Figure 10 shows the details of how the GetName method of the SelectPart part is called from the GetName method of the extension.

Figure 9. Program flow of ImagePart/SelectPart interaction.

Figure 10. Execution of the GetName method.

SOM Interface

To get the advantages of a cross-platform development system, it is necessary to isolate the program code from the interface code. This is done in OpenDoc by writing SOM interface code using the IDL (Interface Definition Language) programming language. The interface code bridges the gap between SOM and high level programming languages such as C++ which are used to write the program proper.

SOM has several components, the most important of which are the SOM kernel, the SOM class libraries and the SOM compiler. The kernel implements the basic runtime behavior while the class libraries augment the runtime environment. The compiler translates the IDL code into a target language such as C++.

The first step towards creating a part is to write a definition file using IDL. The file will be identified with an .IDL suffix. The format of a typical class definition taken from Apple's SamplePart project is as follows:

module SampleCode
 interface som_SamplePart : ODPart
 majorversion = 1; minorversion = 0;
 functionprefix = som_SamplePart__;

#ifdef __PRIVATE__
 passthru C_xih = "class SamplePart;";

 SamplePart *fPart;
#endif //__PRIVATE__
...More stuff that is not used on the Macintosh.

When the .IDL file is compiled, three new files are created. These are a usage binding, an implementation and an implementation template file with extensions .xh, .xih and .cpp respectively. The usage binding file corresponds to a C++ header file. The implementation file is private to the SOM class and contains macros and other information needed for the class to have access to its instance variables and superclass methods. The implementation template file corresponds to a regular C++ implementation file. Basically, it contains stub method definitions which must be filled in by the programmer.

Programming Level

The following code was tested using OpenDoc release DR5, CodeWarrior, version 9 and System 7.5.2. Create two new OpenDoc part projects using PartMaker Pro. Configure them as follows.


The ImagePart part is created using Apple's SamplePart template. Use the names ImagePart and KSS for class and module identifiers respectively. The following method is added to the ImagePart class and called by adding a line of code to the end of the InitializePartFromStorage (or InitPart) method.

void ImagePart::MyOpenPict(Environment *ev)
 ODPart *selectFile;
 ODStorageUnit *su;
 KSS_GetNameExt  *extension;

 su = fSelf->GetStorageUnit(ev);
 selectFile = 0L;
 selectFile = su->GetDraft(ev)
 ->CreatePart(ev, kSelectPart, kODNULL);
 hasExt = selectFile->HasExtension(ev, kGetNameExtension);
 if (hasExt)
 extension = (KSS_GetNameExt*)selectFile
 ->AcquireExtension(ev, kGetNameExtension);
 extension->ReleaseExtension(ev); // Not tested.

This #include statement is put at the top of the ImagePart.cpp file:

#include "GetNameExt.xh" // This can go anywhere.

Add these lines to the ImagePart.h file.

//-*** Programmer added material ***
 void MyOpenPict(Environment *ev);

The indicated changes are made to the ImagePartDef.h file.

// SelectPart items
#define kSelectPartKind   "Apple:Kind:SelectPart"
#define kGetNameExtension \
 "Apple Computer:Extension:ScriptGetName"

At this point, set aside the ImagePart project until the SelectPart project has been compiled and the SelectPart.stub and GetNameExt.h files have been created.


The next step is to get our ducks in line on the receiving end. Create the SelectPart project using Apple's ScriptRunner template. Use SelectPart and KSS for class and module identifiers respectively. Locate the following lines of code in the SelectPart.idl file, which are located immediately after the following line.

interface som_SelectPart : ODPart

 void   ShowPalette();
 void   HidePalette();
 ODBooleanMovePalette(in ODPoint point);
 ODPoint* GetPaletteLocation();
 void   SetClient(in ODPart client);
 void   HandleRecordingEvent(in AEDesc script);

and replace them with

 void GetName();

Now, locate the following lines immediately after releaseorder.


and replace ShowPalette to HandleRecordingEvent with


The finished .idl file will be as follows:

module KSS
 interface som_SelectPart : ODPart


 void GetName();
#ifdef __SOMIDL__

#ifdef __PRIVATE__
 passthru C_xih =
 "class SelectPart;";

Compile the file using the instructions given in the next section.

When completed, you will have three output files entitled SelectPart.cpp, SelectPart.xh and SelectPart.xih. Replace the .xh and .xih files in the SelectPart project source folder with the new ones.

Do not replace the .cpp but rather open the original one found in the source folder and delete the methods ShowPalette, HidePalette, IsPaletteVisible, MovePalette, GetPaletteLocation, SetClient and HandleRecordingEvent. Comment out the command somSelf->HidePalette(ev) and associated code in the HandleEventWindow method. Open CScripter.cpp and comment out the call to HandleRecordingEvent in the method, RecordEventHandler. Open the new .cpp file and locate the GetName method. Use this code as a model for adding a GetName method to the original SelectPart.cpp file. The resulting addition should be as follows.

SOM_Scope void SOMLINK SelectPart__GetName(KSS_SelectPart *somSelf,
 Environment *ev)
 Point  where;
 SFTypeList typeList;


 where.h = 40;
 where.v = 40;
 ODSLong rfRef;
 rfRef = BeginUsingLibraryResources();
 ::SFGetFile(where, 0L, 0L, -1, typeList, 0L, 

Put #include "StandardFile.h" somewhere so that SFGetFile will work.


Locate the files PaletteExt.idl, PaletteExt.cpp, PaletteExt.xh, PaletteExt.xih and paletteExt.exp and change their names to GetNameExt.idl, GetNameExt.cpp, etc. Do a global search in the text of these files with an editor such as BBEdit and replace all instances of PaletteExt and Samples with GetNameExt and KSS respectively. Similarly locate and replace any instances of kPaletteExtension found in the SelectPart project (all the files in the source folder) with kGetNameExtension. We are now ready to modify and compile the GetNameExt.idl file.

Locate the following lines in the GetNameExt.idl file:

 void   Show();
 void   Hide();
 ODBooleanMove(in ODPoint topleft);
 ODPoint* GetLocation();
 void   SetClient(in ODPart client); 

Replace them with:

 void   GetName();

Also locate:


and replace them with:


Following SOM compilation, go back to the source folder of the SelectPart project and replace GetNameExt.xh and GetNameExt.xih with the newly generated files. Open the SelectPart project and replace PaletteExt.cpp and Palette.exp with GetNameExt.cpp and GetName.exp. Open the original GetNameExt.cpp file and remove the code for the Show, Hide, IsPaletteVisible, Move, GetLocation and SetClient methods. Next open the new GetNameExt.cpp file and copy the code over for the GetName method to the original GetNameExt.cpp file. This code should be as follows.

SOM_Scope void
SOMLINK GetNameExt__GetName(Samples_GetNameExt *somSelf, Environment 
 Samples_GetNameExtData *somThis = 
 "Get NameExt__GetName");

Compile the SelectPart project.


Create a file named SelectPart.stub as follows.

1. Make a copy of the SelectPart library and name it SelectPart.stub.

2. Open SelectPart.stub using ResEdit. Open the ‘cfrg' resource.

3. Change the member count of the ‘cfrg' resource to 1.

4. Delete the second member of the ‘cfrg' resource.

5. Save the resource.

Move the SelectPart.stub file to the Objects folder of the ImagePart project folder. Make a copy of the GetNameExt.xh file and move it to the source folder of the ImagePart project folder. Open the ImagePart project, create a category named SelectPart Library and add SelectPart.stub to the project. Compile the ImagePart project.

Create stationary files from the ImagePart and SelectPart libraries. Go to the stationary folder and execute the ImagePart stationary. It will bring up a dialog box asking for a file name.

At this point, you are ready to start creating your own parts which use customized extensions.

SOM Compilation

Once the requested changes have been made, the .idl files are compiled with MPW Shell or ToolServer. The major problem is that these programs do not keep track of header files. This means that the programmer must know what and where everything is in his OpenDoc project. This requirement usually overwhelms anyone using these programs for the first time (or the second, or the third).

We have found that the easiest (not best) work-around for the directory problem, is to put everything into the main MPW directory. The equivalent operation with ToolServer is probably to place the project folder in the directory containing ToolServer. The best method, of course, is to become proficient with MPW Shell and/or ToolServer. Instructions and scripts on how to use ToolServer can be obtained from Symantec and Metrowerks. In addition, there are two articles dealing with this subject in recent issues of Develop. (See further reading.)

We used the following script based on the Internet tech note by Jeremy Roschelle to compile our .idl files. (See further reading.)

set SOMOUT ‘ PowerBook1:MPW:OpenDoc Projects:SOM Support'
set ODIDL ‘ PowerBook1:MPW:OpenDoc Projects:Interfaces:IDL'
set ODDIRS "-i ‘{ODIDL}'"
set TARGET ‘ PowerBook1:MPW:OpenDoc Projects:IDL'
somc {ODDIRS} -p -e xih,xc,xh -o "{SOMOUT}" " PowerBook1:MPW:OpenDoc 

SOMOUT is the path to where we want our output files to be placed. ODDIRS is the location of the OpenDoc .idl files. If you don't know where to find them, search for the file arbitrat.idl on the OpenDoc and compiler disks and copy them to the above directory. TARGET was included for completeness. It is the pathway to your .idl source file. MPW Shell has a bug which prevented its use so we addressed the location of the file with its full path name (end of somc command line). SamplePartVers.h must be placed in this folder also.


And there it is. You can add an extension to your part by making minor changes to two .idl files. You then make further minor changes to the original .cpp and .h files. The resulting code will be stable and eventually you will be able to port across platforms.


We wish to thank the folks at Metrowerks, Mainstay and Bare Bones for CodeWarrior, MacFlow and BBEdit respectively. Without these programs, life would be much harder.

Further Reading

Recent articles that are relevant to this article.

Apple Computer, "OpenDoc Cookbook for the Macintosh", Addison-Wesley: Menlo Park, CA, (1996). (Also OpenDoc Developer CD #4 and Apple Developer CDs.)

Apple Computer, "OpenDoc Programmer's Guide for the Apple OS", Addison-Wesley: Menlo Park, CA, (1996). (Also OpenDoc Developer CD #4 and Apple Developer CDs.)

Kenner, G., and D. Kenner, "Using OpenDoc with Object Flow System (OFS)," MacTech Magazine, 12:2(1996) 40-46.

Kenner, G., and D. Kenner, Object Flow System (OFS) for Visual C++, unpublished manuscript, 1995. (Request via email.)

Maroney, T., ToolServer Caveats and Carping, Develop, 24 (1995) 69-71.


Community Search:
MacTech Search:

Software Updates via MacUpdate

Sago Mini Superhero (Education)
Sago Mini Superhero 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: KAPOW! Jack the rabbit bursts into the sky as the Sago Mini Superhero! Fly with Jack as he lifts impossible weights,... | Read more »
Star Wars: Galaxy of Heroes guide - How...
Star Wars: Galaxy of Heroes is all about collecting heroes, powering them up, and using them together to defeat your foes. It's pretty straightforward stuff for the most part, but increasing your characters' stats can be a bit confusing because it... | Read more »
The best cooking apps (just in time for...
It’s that time of year again, where you’ll be gathering around the dinner table with your family and a huge feast in front of you. [Read more] | Read more »
Square Rave guide - How to grab those te...
Square Rave is an awesome little music-oriented puzzle game that smacks of games like Lumines, but with its own unique sense of gameplay. To help wrap your head around the game, keep the following tips and tricks in mind. [Read more] | Read more »
Snowboard Party 2 (Games)
Snowboard Party 2 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Crowned the best snowboarding game available on the market, Snowboard Party is back to fulfill all your adrenaline needs in... | Read more »
One Button Travel (Games)
One Button Travel 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: “To cut a long story short, If you like interactive fiction, just go buy this one.” - “Oozes the polish that... | Read more »
Light Apprentice Volume 1 (Games)
Light Apprentice Volume 1 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Light Apprentice Volume 1 includes Chapters 1 to 4, all gathered in a new exclusive game. When life in the world of... | Read more »
The best games like Animal Crossing on m...
Animal Crossing amiibo Festival is out right now for the Wii U, reminding us of just how much fun that world can be. Or at least to go back and check in on our villages once in a while. [Read more] | Read more »
Between 2 Taps - Tap for Tap interview M...
Hello, and welcome back to Between 2 Taps, Tap for Tap’s Indie Dev interview series. [Read more] | Read more »
Facility 47 (Games)
Facility 47 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: You wake up alone and freezing in an icy cell. You try the cell door but it’s locked, it seems that you are stuck with no... | Read more »

Price Scanner via

Black Friday deals on the Apple Watch and App...
Apple resellers are offering discounts and bundles with the purchase of an Apple Watch this Black Friday weekend. Below is a roundup of the deals being offered by authorized Watch resellers: Apple... Read more
Early Black Friday sale at B&H Photo, up...
B&H Photo has all new Macs on sale for up to $500 off MSRP as part of their early Black Friday sale including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1699 $300 off... Read more
NewerTech/OWC/MacSales Black Friday Deals 201... • Free Shipping available on nearly EVERYTHING on orders $35.00 & up within USA + • International Delivery Specials from $2.99+ Special Purolator... Read more
Walmart Black Friday deals: $100 off select i...
Walmart has released their Black Friday deals for 2015, now available online. Choose free shipping or free local store pickup (if available): - 16GB iPad Air 2: $399, $100 off MSRP - 16GB iPad Air: $... Read more
Photo Cleaner 1.0 Reclaims iPhone Storage Spa...
Seoul, Korea based mix1009 has announced the release and immediate availability of Photo Cleaner 1.0, their handy iPhone app that deletes the video portion of Live Photos, in order to reclaim space... Read more
Black Friday and Holiday sales on our price t...
Scan our Mac Price Trackers for the latest Black Friday and Holiday season information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the... Read more
Best Buy Black Friday deals: Up to $200 off M...
Best Buy has posted their Black Friday sale prices for 2015. Save on MacBook Pros, MacBooks, MacBook Airs, iMacs, iPads, and Apple Watches. Choose free shipping or free local store pickup (if... Read more
Save $30-$40 on new Apple TVs after rebate
Adorama has new Apple TVs on sale for up to $40 off MSRP after mail-in rebate, good through December 15th. Shipping is free, and Adorama charges NY & NJ sales tax only: - 32GB Apple TV: $119.99... Read more
13-Inch Haswell MacBook Air At Two Years – Th...
The 13-inch mid-2013 “Haswell” MacBook Air I ordered in Apple’s November 2013 Black Friday sale was my first new Mac in four and a half years — the longest interval I’ve gone between system upgrades... Read more
Target Black Friday Early Access deals: $100...
Target is offering early access to their Black Friday deals on Apple products on their online store for today, the 25th, only. Choose free shipping or free local store pickup (if available): - Apple... Read more

Jobs Board

*Apple* Enterprise / Government Professional...
# Apple Enterprise / Gove ment Professional Services Engineer Job Number: 42292976 Reston, Virginia, United States Posted: Aug. 18, 2015 Weekly Hours: 40.00 **Job Read more
iOS Wallet & *Apple* Pay Engineer - App...
# iOS Wallet & Apple Pay Engineer Job Number: 40586801 Santa Clara Valley, Califo ia, United States Posted: Nov. 16, 2015 Weekly Hours: 40.00 **Job Summary** The iOS Read more
Software Engineer, *Apple* Watch - Clock Fa...
# Software Engineer, Apple Watch - Clock Face Team Job Number: 44368761 Santa Clara Valley, Califo ia, United States Posted: Nov. 14, 2015 Weekly Hours: 40.00 **Job Read more
Administrative Assistant, *Apple* Online St...
# Administrative Assistant, Apple Online Store Job Number: 43992352 Santa Clara Valley, Califo ia, United States Posted: Nov. 9, 2015 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.