Programming Guide: The OpenDoc Class Library

# Programming Guide

## The OpenDoc Class Library

OpenDoc is a set of DLLs with a largely platform-independent, object-oriented programming interface. This section introduces the classes implemented in the OpenDoc libraries and the design goals behind them.

The interfaces to all of OpenDoc's classes are specified in the Interface Definition Language (IDL), a programming-language-neutral syntax for creating interfaces. IDL is part of the System Object Model (SOM), a specification for object binding at runtime. IDL interfaces are typically compiled separately from implementation code, using a SOM compiler. See "Developing with SOM and IDL" for more information.

Because OpenDoc uses IDL and SOM, part editors and other OpenDoc objects created with different compilers or in different languages can communicate. Also, they can be independently revised and extended and still work together.

For more complete information on the OpenDoc class library, including detailed descriptions of all public OpenDoc classes and methods, see the OpenDoc Programming Reference.

### A Set of Classes, Not a Framework

OpenDoc is a set of classes whose objects cooperate in the creation and manipulation of compound documents. It is designed to be as platform-neutral as possible. The object-oriented library structure, in which object fields are private, facilitates the replacement of existing code in a modular manner. Also, by using abstract classes and pure virtual methods, it defines a structure for part editors while specifying as little as possible about their internal functioning.

The OpenDoc class library is not an object-oriented application framework in the full sense of the word. That is, even though the design of OpenDoc allows you to create a part editor, it does so at a lower level, and without forcing as much adherence to interface and implementation as is typical for an application framework.

You can create a part editor just as effectively in either way: directly to the OpenDoc library interfaces or indirectly through the interfaces of a framework. The main difference is that if you use a part-editor framework, you have less code to actually implement yourself, and it is easier to ensure consistency in the final product.

The principal classes in the OpenDoc class hierarchy are shown in Figure 22. All classes are derived from the superclass ODObject, itself a subclass of somObject, the fundamental SOM superclass (not shown). The figure shows these categories of classes:

- Names in bold represent abstract superclasses that your part editor is likely to subclass.

- Names in italics represent classes whose objects your part typically creates for its own use. You create these objects by calling methods described in "Factory Methods".

- Names in plain text represent classes whose objects your part editor calls but typically never has to create; they are created for you by OpenDoc.

Figure 22. OpenDoc Class Hierarchy (Principal Classes)

View figure.

For an illustrated discussion of the relationships of the principal OpenDoc objects in terms of runtime references among them, see "Run-Time Object Relationships".

Classes shown in Figure 23 are support classes, consisting mostly of iterators and simple sets. They are all direct subclasses of ODObject.

Figure 23. OpenDoc Class Hierarchy (Support Classes)

View figure.

Compared to some application frameworks, there is little inheritance in the hierarchy represented in Figure 22 and in Figure 23; OpenDoc instead makes extensive use of object delegation, in which objects unrelated by inheritance cooperate to perform a task. This relatively flat inheritance structure preserves the language-neutral flavor of OpenDoc and improves ease of maintenance and replaceability.

The OpenDoc classes can be divided into these three groups, based on how a part editor might make use of them:

- The class (ODPart) that you must subclass and implement to create your part editor
- The bulk of the implemented OpenDoc classes, whose objects are created either by your part editor or by OpenDoc, that your part editor calls to perform its tasks
- The classes you can subclass and implement to extend OpenDoc

The following sections summarize these groups of classes.

### Classes You Must Subclass

The OpenDoc classes listed in this section are abstract superclasses that you are intended to subclass if you wish to implement their capabilities.

The class ODPart is central to OpenDoc; it is the one class that you must subclass to create a part editor. ODPart represents the programming interface that your part editor presents to OpenDoc and to other parts.

ODPart is an abstract superclass with many defined methods. When you subclass ODPart, you must override all methods, but you need to provide meaningful implementations only for those methods that represent capabilities actually supported by your part editor. The rest can be stub implementations.

If your part is a container part you must provide an iterator class (a subclass of the abstract superclass ODEmbeddedFramesIterator) to allow callers to access all of the frames directly embedded in your part. Also, Metaclass M-ODPart is required to register your part with OpenDoc.

### Classes for Extending OpenDoc

OpenDoc provides these classes specifically for enhancing its features:

- The class ODExtension is the abstract superclass from which extensions to OpenDoc are defined; OpenDoc allows you to add new methods to existing classes by associating objects of class ODExtension with the specific class that they extend. The classes ODScriptExtension and ODSettingsExtension are examples of currently existing subclasses of ODExtension.

- The class ODScriptExtension, when subclassed, represents the interface through which a part supports attached scripts that allow the part to be scripted using a script component.

- The class ODSettingsExtension, when subclassed, represents an object with which your part editor can create and display a Settings dialog box for your part editor.

- The class ODDispatchModule is used to dispatch certain types of events (such as keystroke events) to part editors. You can provide for dispatching of new types of events or messages to your part editor by subclassing ODDispatchModule.

- The class ODFocusModule is used to describe a particular type of focus (such as the selection focus). You can provide new types of focus for your part editor by subclassing ODFocusModule.

- The class ODTransform represents a graphical transformation matrix used for drawing. You can subclass it to extend the kinds of transformations it can perform. This class is somewhat different from the other classes in this category, because it can be used as is; for this reason, the class also appears in the next section.

### Classes You Can Use

The OpenDoc classes listed in this section implement most of the OpenDoc features that your part editor uses. By using or instantiating objects of these classes, your part can function within an OpenDoc document and can embed other parts.

#### Abstract Superclasses

These classes are never directly instantiated. The classes ODPart and ODEmbeddedFramesIterator, mentioned in the previous section, are abstract superclasses. Other abstract superclasses are mentioned in "Classes for Extending OpenDoc".

The abstract superclasses in the following list are special. They define the basic inheritance architecture of OpenDoc. You should not instantiate these classes and probably would never directly subclass them. In developing a part editor, you would use or subclass one of their existing subclasses.

- ODObject. This is the abstract superclass for most of the principal OpenDoc classes. All subclasses of ODObject define objects that are extensible.

- ODRefCntObject. This is the abstract superclass for reference-counted objects. These are objects that maintain a count of other objects that refer to them in order to manage memory efficiently.

- ODPersistentObject is the abstract superclass for persistent objects. A persistent object's state can be stored persistently.

#### Implemented Classes

These classes are implemented in ways unique to each platform that supports OpenDoc. Some represent objects that are created only by OpenDoc, whereas others represent objects that your part editor may need to create.

- The session object. The class ODSession represents the user's opening of and accessing to a single OpenDoc document.

  There is only one ODSession object. Part editors and other OpenDoc objects cache a reference to the single ODSession object for performance reasons. The OpenDoc run time calls ODSession to instantiate all of the OpenDoc library objects (such as ODDispatcher, ODWindowState, and ODArbitrator) and initialize them. ODSession also keeps internal references to these OpenDoc objects, so it is a handy thing to use to access other objects.

- The binding object. The class ODBinding represents the object that performs the binding of part editors to the parts in a document. The binding process determines which part editor to use for a part.

- Storage classes. The primary classes of objects associated with document storage are the class ODStorageSystem and the set of classes (ODContainer, ODDocument, ODDraft, and ODStorageUnit) that constitute a container suite. The container-suite objects all work closely together and are implemented differently for each platform or file system.

- Data-interchange classes. The classes ODLink, ODLinkSource, ODLinkSpec, ODDragAndDrop, and ODClipboard all relate to transfer of data from one location to another. These objects do not represent documents, but they nevertheless use storage units to hold the data they transfer.

- Drawing-related classes. The classes ODCanvas, ODShape, and ODTransform represent imaging structures in a given graphics system. The classes ODWindowState and ODWindow represent windows on a given platform. The classes ODFrame and ODFacet represent the frame and facet structures that define the layout of embedded parts.

- Event-handling classes. The classes ODArbitrator and ODDispatcher control what kinds of user events are sent to which part editors during execution. The classes ODMenuBar, ODPopupMenu, and ODUndo give part editors access to the user interface.

#### Service Classes

These classes exist mainly as services for other classes to use:

- The ODStorageUnitCursor and ODStorageUnitView classes facilitate access to specific values in specific storage units.

- The ODFocusSet class provides convenient grouping of focuses (access to shared-resources such as the keyboard or menu bar) for activation and event handling.

- The ODNameSpaceManager and ODNameSpace classes provide convenient storage for attribute/value pairs. The classes ODObjectNameSpace and ODValueNameSpace, subclasses of ODNameSpace, provide, respectively, name spaces for OpenDoc objects and for data.

- Many classes have associated iterator classes and list classes that are used for counting through all related instances of the class.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]