Programming Guide: The Document Shell

# 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:

- It creates and initializes the session object.

- It opens a document (as instructed by the user) from storage, and provides a window for it.

- It accepts user semantic events, and passes them to the OpenDoc dispatcher.

- It handles most items on the Document menu.

#### 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 79 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 79. Document Menu

View figure.

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

- New document. The document shell creates a new, blank document whose root part is of the same part kind as the root part of the current document. The shell then opens the document in a separate document window. When a document containing your part opens, your part receives several method calls, as described in "Opening a Document" and "Initializing and Reading a Part from Storage".

- Open document. The document shell displays a file-navigation dialog box through which the user selects a document to open. The document opens in its own window.

- Save document. The document shell saves the current document.

- Save a copy. The document shell saves a copy of the draft belonging to the active window into a new file. The document shell displays a file navigation dialog box to allow the user to specify the name and choose a location. The current document remains open.

- Revert to saved. The document shell reopens the last saved version of the current document, replacing the presently open version of it.

- Drafts -> Create draft. The document shell displays the Create draft dialog box, through which the user creates a new draft of the document.

- Drafts -> Draft history. The document shell displays the Draft history dialog box, through which the user can view or delete previous drafts of the document. An example of the Drafts History window is shown in Figure 15.

- Document properties. The document shell brings up the Properties notebook of the root part, shown in Figure 80.

  Figure 80. Document Properties Notebook on OS/2 (Page 1)

  View figure.

  5i'.

  Figure 81. Document Properties Notebook on OS/2 (Page 2)

  View figure.

  5i'.

  Figure 82. Document Properties Notebook on OS/2 (Page 3)

  View figure.

  5i'.

  Document Properties Notebook is shown on the Windows platform in Figure 83.

  Figure 83. Document Properties Notebook on Windows (Page 1)

  View figure.

  Figure 84. Document Properties Notebook on Windows (Page 2)

  View figure.

  Figure 85. Document Properties Notebook on Windows (Page 3)

  View figure.

  The user can then perform several actions, including changing the view type, part kind, and editor for the root part.

- Page setup. (Handled by the root part; see "Document Menu").

- Print document. (Handled by the root part; see "Document Menu").

- Close. If the user selects Close on the document window that contains the current draft, the docshell closes the document along with all of its associated windows. If the user selects Close from another window (for example, a part window) the docshell closes that window, leaving all other windows in place.

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