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.
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
All figures in this book that illustrate run-time object relationships use the following conventions:
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.
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.
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.
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.
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
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.
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.
Figure 72. General Embedding Object Relationships
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.
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
Each display frame object for the part being drawn can include references to these objects:
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:
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".
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:
Figure 74. User-Interface Object Relationships
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.
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
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:
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".
Figure 76 shows additional object references maintained by the part object, beyond those shown in Figure 72 that facilitate data transfer.
Figure 76. Part-Storage Relationships
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".
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.
Figure 77. Part-Extension Relationships
If a part supports scripting, it has a reference to its scripting interface object, an extension object implemented as part of OpenDoc.