Title Banner

Previous Book Contents Book Index Next

Inside Macintosh: OpenDoc Programmer's Guide / Part 2 - Programming
Chapter 11 - OpenDoc Runtime Features


The Document Shell

The document shell is the OpenDoc object responsible for handling document-
wide and draft-wide operations. It is the closest OpenDoc runtime 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 runtime 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 on the Mac OS platform, 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 a shared library called the OpenDoc document shell. Individual part editors implicitly use this shared code in the document. 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 the user opens a document, 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.)

If the user specifies that a document is to be saved as stationery, the document shell sets a flag in the document file to notify the operating system that a document is stationery instead of an ordinary OpenDoc 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 its last document window closes. 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 its state as of the last save.

Handling User Events

The document shell receives all user events directly and ensures 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 Chapter 5, "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 used by OpenDoc documents and parts.

The document shell can handle standard Mac OS window events, such as a click in the close box, although the dispatcher gives the root part of the window a chance to handle such events first. See "Handling Window Events" for more information.

Menu events go first to the document shell; the shell handles most Document menu commands and passes others (see "The Document Menu"

Handling Semantic Events

Semantic events sent to a part in a document are received first by the document shell and then passed to the dispatcher to be distributed in the same manner as user events. See "Writing Semantic-Event Handlers" for more information.

The document shell has its own semantic interface, through which it handles the required set of Apple events. See the note "Document shell semantic interface"

The Document Shell and the Document Menu

Figure 11-12 shows the standard OpenDoc Document menu on the Mac OS platform. 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 the section "The Document Menu" for a discussion of the user-interface considerations related to the Document menu and its items.

Figure 11-12 The Document menu




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

Figure 11-13 Save a Copy dialog box




The Save a Copy dialog box also allows the user to specify a part kind for the root part. If your part is saved through this command, your part editor receives a call to its ExternalizeKinds method; see "The ExternalizeKinds Method" for an explanation.

Figure 11-14 Document Info dialog box




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

The dialog box also contains these three checkboxes:


Previous Book Contents Book Index Next

© Apple Computer, Inc.
16 JUL 1996




Navigation graphic, see text links

Main | Top of Section | What's New | Apple Computer, Inc. | Find It | Feedback | Help