Inside Macintosh: Programmer's Guide to MacApp / Part 1 - MacApp Theory and Architecture

Chapter 7 - Document Handling

MacApp's Document Classes

As the hierarchy in Figure 7-1 shows, each of MacApp's document classes descends from the TCommandHandler class and each inherits from the MScriptableObject class. As a result, each of MacApp's document classes is capable of creating commands to respond to user actions and of working with Apple events.

MacApp provides the following document classes for your application to build on:

TDocument

The TDocument class is an abstract class that defines methods for performing basic document operations.

TFileBasedDocument

The TFileBasedDocument subclass of TDocument adds methods for working with disk files. TFileBasedDocument is a suitable parent class for many standard documents.

TEditionDocument

The TEditionDocument subclass of TFileBasedDocument adds Edition Manager support for publishing and subscribing. Applications that use publish and subscribe can define a subclass of TEditionDocument.

TMailableDocument

The TMailableDocument subclass of TFileBasedDocument adds support for turning a document into an electronic mailer. If your application needs to take advantage of MacApp's PowerTalk mailer support, you can define a subclass of the TMailableDocument class.

TTEDocument

This subclass of TMailableDocument is defined in the DemoText sample application. While not a part of the MacApp class library, it does demonstrate the use of PowerTalk mailers and many text-editing features.

These document classes are described in greater detail in the sections that follow.

The TDocument Class

The TDocument class is an abstract class--you don't normally instantiate objects of this type. Some of the methods defined in TDocument do nothing and are overridden in MacApp's document subclasses.

Most of MacApp's document classes are designed primarily for working with disk-based documents. If your application requires other types of documents, such as documents contained in databases or documents contained inside other documents, you can define a subclass of TDocument.

The TDocument class provide basic services, such as creating a document's views, setting up its menu items, and handling document-related menu commands, including Save, Save As, Save a Copy, and Revert to Saved. TDocument also mixes in the MScriptable class, so any subclass of TDocument can be a target for Apple events and can return contained objects. The MScriptable class is described in Chapter 6, "Scripting."

TDocument defines these methods for responding to Apple event object-specifier queries: GetContainedObject, GetObjectProperty, and SetObjectProperty. These methods can handle certain requests themselves and pass others on to the mixin MScriptable class.

TDocument also defines these methods for handling Apple events: DoAEClose, DoAEPrint, and DoAESave. These methods create command objects to handle the specified operation. For example, DoAEClose creates a TCloseDocCommand object to close the document.

The TFileBasedDocument Class

The TFileBasedDocument class is a subclass of TDocument that adds fields and methods for reading a document from a file, writing a document to a file, and determining how much room a document will take on disk. If the document has an attached script, the TFileBasedDocument class can write the script to the document's resource fork or read it from the resource fork.

TFileBasedDocument works with the TFileHandler and TFile classes. TFile provides a convenient interface to files on disk. TFileHandler contains much of the code for saving and opening file-based documents. TFileBasedDocument and TFileHandler are so tightly integrated that they can be thought of as two parts of the same object. Files and file handlers are described in greater detail in "Document Operations," beginning on page 168.

Subclasses of TFileBasedDocument typically override methods for reading and writing data and for determining how much room data will require on disk. TFileBasedDocument also overrides DoAEClose to create a TCloseFileDocCommand object to close the document. For recipes and code samples that demonstrate how to work with file-based documents, see Chapter 16, "Working With Documents."

The TEditionDocument Class

The TEditionDocument class is a subclass of TFileBasedDocument that adds support for publish and subscribe, using the Edition Manager. This class enables and handles the menu commands Create Publisher, Subscribe To, Publisher/Subscriber Options, Show/Hide Borders, and Stop All Editions.

When you define a subclass of TEditionDocument, you don't normally override methods that supply Edition Manager functions. Instead, you override methods involved in reading, writing, or displaying your document's edition data.

MacApp's Edition Manager support is described in detail in "Publish and Subscribe," beginning on page 184. Recipes and code samples are provided in Chapter 31, "Working With the Edition Manager." Edition Manager support for publish and subscribe is demonstrated in the Calc sample application.

The TMailableDocument Class

The TMailableDocument class is a subclass of TFileBasedDocument that adds methods for working with a document as electronic mail, using MacApp's PowerTalk support. Working with the mixin class MMailable, which in turn works with the TFileBasedLetter class, the TMailableDocument class enables and handles the Mail menu commands Add/Delete Mailer, Send, Reply, Forward, and Open Next Letter.

Any document object based on the TMailableDocument class can be turned into an electronic mailer. Subclasses of TMailableDocument typically override methods for supplying or extracting their own data, such as AddStandardMailContent, ReadStandardMailContent, and SetReplyContents. The TTEDocument class from the DemoText sample application provides a detailed example of a mailable document class. TTEDocument is described in the next section.

For more information on mailers, see "PowerTalk Mailers," beginning on page 192. Recipes and code samples are provided in Chapter 29, "Working With PowerTalk Mailers."

The TTEDocument Class

The TTEDocument class is a subclass of TFileBasedDocument that adds fields and methods for handling text and text-editing views, as well as for adding a PowerTalk electronic mailer to a document. This class demonstrates how to write text data to a file and read it back. It also demonstrates how to read and write mailer data in various formats. The TTEDocument class is not a part of MacApp itself, but is defined in the DemoText sample application. You can read more about the TTEDocument class in Chapter 29, "Working With PowerTalk Mailers."