Programming Guide

The Document Shell

   

The document shell is the OpenDoc object that is responsible for handling document-wide and draft-wide operations. It is the closest OpenDoc run-time equivalent to a conventional application, although the same document shell handles all kinds of OpenDoc parts and documents. One of its main responsibilities is to accept events from the operating system and pass them on to OpenDoc for dispatching. Another is to handle certain menu items.

This section summarizes the run-time operations and responsibilities of the document shell and its relationship to part editors. It also describes how the document shell handles commands from the Document menu.

The discussion in this section is largely for informational purposes; your part editor never has to call the document shell.

Document Shell Operations

     

In OpenDoc, the document, not any application, is the owner of the process in which the document is opened. Under OpenDoc the document manages standard tasks like handling the event loop, managing files, and interacting with system menus, dialog boxes, and so on. This behavior is provided by an executable called the document shell. Individual part editors implicitly use this code in the document shell. For this reason, part editors can be significantly smaller than conventional applications. However, part editors must cooperate with each other in ways that conventional applications normally do not.  

The document shell represents the process in which the parts of a single OpenDoc document execute. It is instantiated when an OpenDoc document is launched, and it is released when the document is closed. The document shell's basic responsibilities are the following:          

Opening a Document

     

When a document is opened by the user, OpenDoc generates a new process that instantiates the document shell. The document shell instantiates the session object, which in turn instantiates the globally available OpenDoc objects, such as the arbitrator and the window-state object. The document shell then opens the document file, and reads the document object and its most recent draft object into memory. The document shell then reads in the draft's window-state object to reconstruct the document's windows. For each window, the window state reads in the root frame.            

The root frame for the window reads in the root part. The root part creates and registers the window, determines which of its embedded frames are visible, reads them in, and constructs facets for them by calling the root facet's CreateEmbeddedFacet method. The embedded frames read their own parts. Those parts in turn read in their embedded frames and create facets for them, and so on until all visible frames, parts, and facets have been read from storage.    

Once all of the necessary objects are read in, OpenDoc asks each facet to draw itself; the part editor of the facet's frame draws the part content that is visible in the facet.

Saving and Reverting a Document

       

When the user saves a document, the draft object asks each part in the document to write itself to the document file. Each part writes its data and references to its embedded frames. The document shell then writes the window state to the document file.

When a document is saved, its data is saved in the context of the current draft. (Each draft of a document includes its own window state, allowing the user to open earlier drafts for viewing at any time).

A stationery document is created by setting the stationery button in the Properties Notebook associated with the root part of the document.    

Reverting a draft means throwing away any changes that have been made since the last save. The document shell releases the existing window state and restores the window state from the previously saved draft. As a result of reverting a draft, the active part and thus the selection and user-interface elements may change.

Closing a Document

   

The document shell closes a document when the document window that contains the current draft is closed. As a result of this closing, some other OpenDoc document window may become active, with its own active frame and selection.

If changes are to be saved when the document closes, the document shell follows the procedures described in the previous section. If the user closes a document without saving changes to the current draft, the document shell releases the window state, leaving the document in the state it occupied at the last save.

Handling User Events

   

The document shell receives all user events directly and is responsible for seeing that events intended for individual parts get to the proper part editor.

The document shell passes all events to the dispatcher for dispatching to the appropriate part, without first classifying them. The dispatcher rejects events it can't identify, returning them to the shell to handle.

To dispatch an event, the dispatcher locates the appropriate dispatch module for the event and asks it to dispatch the event. The dispatch module actually distributes the event to the appropriate part or document, in cooperation with the window state and the arbitrator, using the facet hierarchy. (See "User Events" for more information).

Part of the document shell's event-handling job is to provide information to part editors about mouse tracking. The document shell also supplies the basic menu bar and pop-up menu used by OpenDoc documents and parts.

Menu events go first to the document shell; the shell handles most Document-menu commands, and passes others (see "Document Menu") to the dispatcher for sending to the appropriate part.  

The Document Shell and the Document Menu

 

Figure 78 shows the standard OpenDoc Document menu. The OpenDoc document shell creates the standard document menu and handles most items in it. Items not handled by the document shell are handled by the root part or the active part, as described in "Document Menu".

Figure 78. Document Menu



View figure.

Here is how the document shell handles each item in the menu:

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