Programming Guide

Run-Time Object Relationships

The run-time state of an OpenDoc document involves relationships among a variety of objects instantiated from the OpenDoc classes (see Figure 21 and Figure 22). Taken together, the diagrams in this section show the principal run-time relationships among the major OpenDoc objects for a single document. The details of the interactions among the objects is explained throughout the rest of this book.

The objects are instantiated from groups of classes called subsystems. OpenDoc is distributed as a set of subsystems. Platform developers, in providing OpenDoc on a given platform, can implement or replace individual subsystems. Part-editor developers generally need not be concerned with the characteristics of specific subsystems. For information purposes, however, subsystem boundaries are shown on the run-time object diagrams presented in this section.

Session Object

When an OpenDoc document is open, the session object occupies a central place in the relationships among the objects that constitute, support, and manipulate the document.   Figure 70 shows the uppermost levels of that relationship.

Figure 70. Run-Time Relationships of the Session Object

View figure.

All figures in this book that illustrate run-time object relationships use the following conventions:

• Individual objects are represented as labeled oval boxes.

• Arrows between the boxes show object references (equivalent to pointers in C++), as defined primarily by the availability of accessor functions for them in the public interface to OpenDoc. The references as shown here may not strictly mirror the actual (private) references that exist between OpenDoc objects. (Various shades or patterns used on the arrows are for visual distinction only; they do not imply different kinds of object references).

• A mutual reference between a pair of objects is represented by an arrow with a head on each end.

• A one-to-many relationship, in which one object can simultaneously reference more than one other object of a given kind, is represented by an arrow with a double head on one end.

• In diagrams that show an embedding hierarchy (such as Figure 72), objects lower in the diagram are embedded more deeply than the objects above them. Objects at the same height are at the same level of embedding.

  As Figure 70 shows, the session object maintains many (mostly one-way) relationships with other objects, allowing your part to gain access to many objects through the session object. The objects are grouped into categories according to the kinds of tasks they perform together; the following subsections discuss and expand upon the object relationships in terms of those categories. Figure 70 is incomplete; Figure 71 and Figure 75 continue the object-reference hierarchy.

Session-Level Objects

As shown in Figure 70, the session object instantiates and maintains direct references to the following objects, accessible globally to all parts in a document.

• OpenDoc uses the binding object to pick the proper part editor for each part in a document, both when the document is opened and whenever a new part is added to it. Binding is further discussed in "Binding".

• Both OpenDoc and part editors use the translation object, a wrapper for available platform-specific data translation services.

• The Name Space Manager keeps track of all name space objects, which themselves contain tables of information needed for registration purposes. See "Name Spaces" for more information.

• The window state object is a list of all the open windows in which OpenDoc parts are displayed. The window state object references each open window; see Figure 71. (The window state object also appears in Figure 74, in relation to others objects of the user-interface subsystem).

• The storage system object, which controls persistent storage for the session. The storage system references one or more container suites; see Figure 75.

• The clipboard object is a session-wide object that represents the clipboard. It references a storage unit that represents the data held on the clipboard.

• The drag-and-drop object is also a single session-wide object. It references a storage unit that represents the data to be transferred by a drag operation.

• The dispatcher accepts user events from the underlying operating system through the document shell and dispatches them to part editors. It references dispatch modules, as shown in Figure 74.

• The arbitrator negotiates temporary ownership of a focus, the designation of a shared resource such as the menu bar, keystroke stream, and so on. It references focus modules, as shown in Figure 74.

• The undo object stores command histories for all parts in the document. It allows parts to reverse or restore the effects of multiple previous user commands. There is a single, session-wide undo object used by all parts in a document.

• The Info object represents the Properties notebook, an extensible notebook used by part editors. Other objects related to extensions are shown in Figure 77.

• The Link Manager keeps track of cross-document links, facilitating the transfer of information between the source and destination parts. The Link Manager is used only by the document shell and container applications; parts never need access to it. The Link Manager is built on platform-specific facilities. Other objects related to links are shown in Figure 76.

If your part needs to access any one of these session-level objects, first obtain a reference to the session object by calling the GetSession method of your part's storage unit. Then call the specific method of the session object (such as GetClipboard) that returns a reference to the needed object. To facilitate repeated access to the session object, you might store the results of GetSession in a part field with a name such as fSession.

Drawing-Related Objects

The objects that make up the OpenDoc drawing capability provide a set of platform-independent protocols for embedding (placing embedded frames within the content of a part), layout (manipulating the sizes and locations of embedded frames), and imaging (making part content and frames visible in a window). They describe part geometry in a document and provide wrapper objects for certain platform-specific imaging structures, whether for printing or for screen display.

Window State and Windows

Figure 71 is a simplification of the run-time object relationships among the objects involved with a document window. It is a continuation of one branch of Figure 70, and shows the upper-level relationships between a window and the parts it contains.  

Figure 71. Window-Related Object Relationships

View figure.

The window state object, referenced by the session object, references one or more window objects, which are wrappers for platform-specific window structures.

Each window object references a single facet object (the root facet), the visible representation of the frame object (the root frame) of the outermost part (the root part) in the document being displayed in the window. The root frame in turn references the root part, which controls some of the basic behavior (such as printing) of the document. The root frame and root facet fill the content region of the window.

This relationship of window to root facet, root frame, and root part applies regardless of whether the window is a document window or a part window opened up from an embedded frame.

The embedding relationships among facets, frames, and parts shown Figure 71 is not complete; it continues down through all parts in the document. The root facet references its embedded facets, and the root part references its embedded frames, as shown in the next section.

Embedding

Figure 72 shows the relationships among facet, frame, and part objects at any level of embedding in a document. It is a direct continuation of Figure 71 but also applies at any level of embedding. In this and all other object diagrams that show embedding relationships, objects lower in the diagram are embedded more deeply than the objects above them.

The first thing to note from Figure 72 is that embedding is represented by two separate but basically parallel structures.

• On the left, each part references one or more display frames above it (the frames within which its contents are displayed) and one or more embedded frames below it. Those embedded frames, in turn, reference the parts for which they are the display frames. The document embedding structure, then, is represented by a frame-to-part, frame-to-part sequence in which each part only indirectly references its embedded parts. Furthermore, an embedded frame does not directly reference its containing part; instead, it references a display frame of its containing part.  

  Figure 72. General Embedding Object Relationships
  

  
  
  View figure.
  
  

• On the right side of Figure 72, the facets for the frames form their own, simpler hierarchy. Each containing facet directly references its embedded facets, and each embedded facet directly references its containing facet. This more direct imaging hierarchy allows for fast event dispatching by OpenDoc.

Connecting the two hierarchies are the frame-to-facet references. Each frame that is visible references the facet or facets that correspond to it. (A frame can have more than one facet). Each facet likewise references its frame. Facets need not exist unless their frames need to be drawn.

For a specific example of this embedding-object relationship in a given document, see Figure 23.

Layout and Imaging

The frame and facet objects shown in Figure 72 have additional references besides those shown. A part's display frame (or frames) and facet (or facets) use several other OpenDoc objects when laying themselves out and preparing to draw the content of their part. Figure 73 shows these additional relationships, for a given frame-facet pair at any level of embedding.  

Figure 73. Layout and Imaging Object Relationships

View figure.

Each display frame object for the part being drawn can include references to these objects:

• A transform object (the internal transform) that defines the geometric offset or transformation of the part within its frame

• A shape object (the frame shape) that defines the basic shape of the frame

• Another shape object (the used shape) that defines the portion of the frame shape that is actually drawn into

• A storage unit, for storing the state of the frame into its document (unless it is a nonpersistent frame)

Each of the facet objects for the part being drawn represents an area within a window (or printer image) that corresponds to a visible display frame (or part of a frame) of the part. The facet can include references to these other objects, which hold platform-specific drawing information:

 
• A canvas object, which describes a platform-specific drawing context or structure  

• A transform object (the external transform) that defines an external geometric offset or transformation for the facet within the containing part

• A shape object that defines the clip shape for the facet (what portion of the frame shape is drawn)      

• Another shape object that defines the active shape for the facet (what portion of the frame shape accepts events)

During the layout and imaging process, a part editor is typically asked to draw the contents of a particular facet. The part editor gets the clipping, transformation, and layout information from the facet and its frame, and then makes platform-specific graphics calls to perform the actual drawing.

For a more complete description of the relationships among frames, facets, and parts, see "Frames and Facets". For a more complete description of the drawing process, see "Drawing".

User-Interface Objects

Run-time relationships in the user-interface subsystem include some objects not directly referenced by the session object. Figure 74 extends a portion of Figure 70 to show these additional objects:

• The window state object references (in addition to all window objects) the menu bar object, which represents the base menu bar created by OpenDoc. Your part copies and adds to this menu bar to create its menus. It also references the pop-up menu object that represents the base pop-up menu created by OpenDoc. Your part copies and adds to this pop-up menu to create its pop-up menus.

• The dispatcher references one or more dispatch modules, which control which frame or part handles each event. The dispatching system is modular; you can extend it to handle new classes of events by adding dispatch module objects.

• The arbitrator references one or more focus modules, which allocate temporary ownership of shared software or hardware resources. Like the dispatcher, the arbitrator is modular; through addition of focus modules, you can extend it to handle new classes of shared resources.

Figure 74. User-Interface Object Relationships

View figure.

Storage Objects

The storage capabilities of OpenDoc include both document storage and data transfer. As Figure 70 shows, five objects directly referenced by the session object are involved with storage issues.

Document Storage

OpenDoc manages persistent storage for parts and other objects in documents. Storage in OpenDoc consists of structured storage elements that can contain many data streams.   Figure 75 shows the main storage-related objects and their run-time relationships. It is a continuation of one branch of Figure 70.

Figure 75. Document-Object Relationships

View figure.

These objects combine to make up a container suite, a specific implementation of the OpenDoc storage architecture. Container suites can be implemented in different ways on different platforms, and need not be limited to file-based systems. Here is how the objects relate to each other:

 
• The storage system object, referenced by the session object, instantiates and maintains a list of container objects. Each container may contain one (or possibly more, depending on the capabilities of the container suite) document objects, each of which represents an OpenDoc document.    

• Each document contains one or more draft objects. Each draft is unique, and represents a snapshot of the document's state at a particular moment.  

• Each draft contains a number of storage unit objects. Each storage unit can contain several different data streams, all of which provide information about the object to which the storage unit applies.     The data streams, or values, in a storage unit are identified by property, name (the kind of information contained) and value type, (the data type of that information). A storage unit can hold more than one property, and a property can hold streams of more than one value type.

Besides being referenced by its draft, each storage unit is also referenced by the object whose data it stores. As Figure 76 shows, for example, a part has a reference to its main storage unit.

Storage units and the storage system are described in more detail in "Storage".

Part Storage

      Figure 76 shows additional object references maintained by the part object, beyond those shown in Figure 72 that facilitate data transfer.

 
• A part object that contains the source of a link references a link source object, instantiated by the part that contains the source data. The link source references (a) a storage unit that holds a copy of the source data for the link and (b) one or more link objects.  

  Figure 76. Part-Storage Relationships
  

  
  
  View figure.
  
  

• A part object that contains the destination of a link references a link object. The link object references a storage unit that holds a copy of the source data for the link. (Links and link sources for an intra-document link share the same storage unit).

Figure 76 also shows how a part must organize the storage of its content.       To store its data in its draft, the part has a reference to its one main storage unit, which in turn can reference other auxiliary storage units.

Storage for data transfer, and other data transfer issues, are described in more detail in "Data Transfer".

Extension Objects and Scripting

OpenDoc provides a flexible method for extending its capabilities through an extension interface. Extensions to objects such as parts provide interfaces through which callers can access additional functionality.

Figure 77 shows additional object references that a part object can maintain, over and above those shown in Figure 76 and Figure 72.    

• Part editors expose their extended interfaces to other parts through an extension object (a subclass of ODExtension). A part can define an extension for any purpose.  

  Figure 77. Part-Extension Relationships
  

  
  
  View figure.
  
  

  If a part supports scripting, it has a reference to its scripting interface object, an extension object implemented as part of OpenDoc.      

• If it provides a custom Settings page, to allow users to change part settings, the part includes a reference to its subclass of the settings extension object. The settings extension is also a subclass of ODExtension.