The OpenDoc OSA Resource Editor

by Eliezer Dekel, Michal Jacovi, and Pnina Vortman

As you probably know from previous articles published in The Developer Connection News, OpenDoc is a compound document architecture, developed by Apple Computer, Inc., that is being incorporated into OS/2 Warp. This compound document architecture is interoperable across multiple platforms (including OS/2 Warp, AIX, Mac System 7, and Windows) and with other similar architectures (such as OLE 2.0 and Taligent).

OpenDoc's compound document architecture implements the notion of document-centric computing, where the document is the center of interaction. Compound documents are documents that comprise information represented by objects of specific types. Objects of specific types are called parts and are managed by a part editor. From the software developer's point of view, OpenDoc is a cross-platform software architecture that enables the development of component software. The term component software describes reusable, compatible building blocks of code that work seamlessly with applications (part editors) from different vendors.

Two fundamental technologies enable the OpenDoc architecture: Developers of new part handlers (applications) and OpenDoc parts need an easy way to define the ICA resources. The OSA Resource Editor gives them an easy and friendly GUI to perform this task.
 * The Interapplication Communication Architecture (ICA), which established the Apple Event User Terminology (AEUT) and Apple Event Terminology Extension (AETE) resources to give applications a way to define events and their semantics in resource files
 * The Open Scripting Architecture (OSA), which is built on the ICA and supports the scriptability of OpenDoc

Scripting Languages
Today, the term scripting language is an ambiguous one. It means HTML or SGML to people that are working on the modern theme of network-centric computing. For system people it means OREXX, Tcl, C-Shell, or Perl, among others. People who use Emacs call it e-lisp, and the users of Word call it Visual Basic.

Scripting languages in various forms have been around for a long time. There were two main streams of progress in scripting languages: operating system directives and application directives (the so-called macro languages). Scripting in the operating system track developed out of the batch control languages and evolved into languages such as Tcl and Perl. Popular applications introduced macro languages for customizing the applications. Notable among these are Lotus Script and Microsoft Visual Basic. In a parallel venue within the application directives track, the languages for directing presentation of information (such as GML and SGML) evolved. The popular major desktop applications (such as spreadsheets, text formatters, databases, and so on) did not come from one vendor. Users, however, wanted to move data from one application to another - in other words, they needed interapplication communication. Users are not satisfied anymore with being able to customize (by an application-specific script) each application and then write a script (in REXX) to bring the applications up in a certain order.

The advent of object-oriented programming allowed the melding of these streams. Document-centric computing with component architectures like OpenDoc and OLE on one end and network-centric computing with DSOM, COM, and Browsers on the other end have put scripting on the main stage.

Open Scripting Architecture
Open Scripting Architecture (OSA) is the a base for future scripting evolution. OSA enables multiple scripting languages and uniform scripting for different applications and is now part of the OpenDoc effort. One of the main differentiators between OpenDoc and OLE is OpenDoc's support of OSA. The scripting language implemented on OS/2 that supports OSA is OREXX.

OSA supports the object model, so the developer can allow direct access to various objects within the application. For example, a spreadsheet application that supports the object model lets a user open a specific spreadsheet, select the second column, calculate its sum, and put the result into another spreadsheet. All that can be performed, of course, through a script. (See Dave Mark's book, Ultimate Mac Programming (see Footnote 5), for discussions on the various levels of OSA support that an application can provide.) In this article, we'll describe how to create the resource (AETE) that externalizes the details of the OSA support in your applications.

The AETE Resource
The AETE Resource is the way an application describes its vocabulary to the rest of the world. It provides information on the kind of objects that the application handles and the actions that can be performed on them. OSA's scripting components use this resource to associate names with internal events in the system. The application's vocabulary (or terminology) is the nouns and verbs that the application supports.

The AETE Resource allows scripting components to interpret scripts correctly and send the appropriate events (verbs) to the application during script execution. If you want your application to be scriptable, you'll have to supply an AETE Resource with it. The verbs and nouns that are in the resource can then be used by script writers when scripting the application. OSA's scripting components use the AETE Resource to interpret the human-language terms used in scripts that control your application and associate them with the corresponding IDs, keywords, and other codes used in events.

The Structure of the Resource
The AETE Resource is a binary file with a strict structure. It consists of several suites that hold the events (verbs) and classes (nouns). The suite is an organizational unit that allows categorization of the objects that an application supports.



Figure 1.

Each suite contains the following information:
 * ID, events, event object classes, comparison operators, and enumerations defined for each suite
 * Parameters defined for each event
 * Properties and elements defined for each object class
 * Key forms defined for each element class
 * Enumerators that provide values for enumerations

AEUT Resource
The AEUT Resource contains terminology information for all the standard suites of events defined in Apple Event Registry: Standard Suites (see Footnote 3). The Event Registry standardizes the vocabulary used by applications and is maintained by CI Labs.

The OSA Resource Editor is a GUI for creating, editing, and browsing AETE Resources. It has a look and feel that is familiar to users of OS/2 Warp (for example, notebooks, icons, drag and drop).

Using the OSA Resource Editot to Create an AETE Resource
The OSA Resource Editor (RED) helps you create your application's AETE Resource with a Workplace Shell-like user interface. This interface will direct you and maintain the correct syntax of your AETE Resource.


 * Starting RED

When you start RED, a folder named RED OSA Resource Editor opens. We call this folder "the editor folder." It contains helpful tools as well as all the AETE Resources being edited. In the editor folder you'll find icons for a Templates folder, a Library folder, and an OSA Aware Applications folder. When you create new resources, or open existing resources, their icons will be added to the editor folder.


 * Browsing an Existing Resource

The best way to get familiar with the OSA Resource Editor and with the AETE Resource is by browsing. You can "snoop" into existing applications. OSA-aware applications (that is, ones that are already installed and are in the OSA database) can be found in the OSA Aware Applications folder. You can bring those into the editor so you can study their structure.

Binary files of AETE Resources can be imported from the Apple Mac platform or created on OS/2. To open them, select Open resource from the RED pull-down menu and a file dialog will appear.

You can also open a resource and browse it. Tree view of the resource gives an overview of the whole tree structure of the resource. Details view of the other objects lets you see the properties of all the contained objects at once.


 * Creating an AETE Resource

To create an AETE Resource, begin by selecting Create resource from the RED pull-down menu on the action bar of the RED OSA Resource Editor folder. A Settings notebook will open for a new resource. In the AETE page of the notebook, you can enter the general information about the resource (such as its major and minor versions, the language code, and the script code). In the File page, enter your application's name (which is also the file stem for saving your AETE Resource) and the path where the resource's file should be saved. Once the notebook has been filled, select the Create push button to create the resource (its icon will be added to the editor folder).

Note: The organization of the terms in your resource directly affect the ability of users to explore and control your application through scripting. For guidelines on designing a good AETE Resource, see appendix C in Ultimate Mac Programming, by Dave Mark.



Figure 2.

The next step is to specify the standard suites that your application supports. In order to do that, double-click on the Library icon in the RED OSA Resource Editor folder. In the Library you can find the set of all standard suites. Using the mouse and Ctrl key, drag the ones your application supports onto the newly created resource. Once the supported standard suites are in the resource, they can be extended or overridden. If you don't want to support a suite as a whole, you can choose one of the following two options: You are now ready to add your own, uninherited objects to the resource. In order to do that, double-click on the Templates icon in the RED OSA Resource Editor folder. In the Templates folder you'll find the Resource template and the set of templates of all kinds of objects that may be in a resource. (Note: The Resource icon cannot go inside a resource, but it is included in the list of icons shown in Figure 3 below for completeness.)
 * If the part you do want to support is rather small, open the suite's Settings notebook and modify the suite's ID to '****'. Then choose the objects you want to support by dragging them from the Library onto the suite.
 * If you want to support most of the suite, delete those objects that you do not want. This will automatically modify the suite's ID to '****', after prompting you to confirm that this is indeed your intention.

Figure 3.

Drag the templates of the desired objects onto your resource. The Resource Editor maintains the strict structure of the AETE Resource by not enabling the drop of a template anywhere in the containment hierarchy, but only in the right place. Thus, you can only drop an event on a suite, a key form on an element, and so on.

There are two additional features of the OSA Resource Editor that are worth mentioning: When working on a new resource, it is helpful to look at the names that are already in use. The dictionary panel provides a list of all the names in the AETE+AEUT name space. Each object window has an Options choice on its action bar. Select Open dictionary from the Options menu to open the dictionary panel. To display a listing, select Open browser on the Options menu. The browser displays a listing of the resource.


 * Saving an AETE Resource

When you have finished editing a resource and you're ready to save it, you can select from two output formats: binary and text. Most of the time you save to a binary file. This binary file can eventually be installed into the OSA aware applications database. It maintains binary compatibility with the Apple Mac platform. Save to a text file if you want a hard copy of the resource. You can enter the name of the file through a file dialog or in the File page in the resource's Settings notebook.

Conclusion
If you are a developer of OpenDoc parts and part editors, you need an easy way to define the ICA resources. The OSA Resource Editor is the way!