Inside Macintosh: Programmer's Guide to MacApp / Part 2 - Working With MacApp

Chapter 16 - Working With Documents

Overview

MacApp provides document classes to store data in memory, to work with views to display that data, to work with files to store data on disk, and to work with the Standard Mail Package to send documents as electronic mail. The class hierarchy for MacApp's document classes is shown in Figure 7-1 on page 164.

If your application doesn't need to save its data to disk, you can define a subclass of TDocument. If it does, you use the TFileBasedDocument class instead. TFileBasedDocument has methods for reading and writing data, which you override to work with your application's specific data.

The TEditionDocument class is a subclass of TFileBasedDocument that adds Edition Manager support for publishing and subscribing.

The TMailableDocument class is a subclass of TFileBasedDocument that adds support for turning documents into electronic mail.

The DemoText sample application defines an additional document class, TTEDocument, a subclass of TMailableDocument. The TTEDocument class implements many text-editing features and also demonstrates how to add custom mailer features to a document using MacApp's PowerTalk support.

Figure 16-1 shows some of the classes and methods you use to work with file-based documents.

Creating and Initializing a Document

This section describes some of the methods MacApp uses to create and initialize a document. Documents are usually created by the application object's OpenNew method. OpenNew calls the application object's DoMakeDocument method to create a new document object. Your application class overrides DoMakeDocument to create and initialize the type of document your application uses.

Your application can set the command number passed to DoMakeDocument by overriding the TApplication::KindOfDocument method, then create different kinds of documents based on the command number. For more information, see "Kinds of Documents," beginning on page 169.

Figure 16-1 Classes and methods used to work with file-based documents

The OpenNew method calls these methods of the document object returned by DoMakeDocument:

• DoInitialState
• DoMakeViews
• UntitledName
• SetTitle
• DoPostMakeViews

These methods are introduced in "Document Operations," beginning on page 168. The following sections add additional information.

The DoInitialState Method

The default implementation of DoInitialState in TDocument does nothing. If your document needs to perform any special initialization after its constructor and its IYourDocument method have been called, you can override DoInitialState.

The TIconDocument class in the IconEdit sample application overrides the DoInitialState method to get an initial icon for the document to display.

The DoMakeViews Method

MacApp doesn't know about your document's internal format, so you override the DoMakeViews method to create views and display the document's data. For more information, see "Creating Views for a Document," beginning on page 174.

The UntitledName and SetTitle Methods

MacApp calls the UntitledName and SetTitle methods of the document object to retrieve the title of the document's window. The default operation of these methods is to set the window title for a new document to "Untitled-n", where "n" is a number equal to 1 plus the number of the last untitled document.

The view resource for a window contains triple angle brackets (<<<>>>) that can be used to specify the window's title. MacApp's default action is to substitute "Untitled-n" for the brackets. You can replace the angle brackets with a title for the window, so that every window created from that resource will have the same name. Or you can place a title in front of or behind the brackets to add something to the default title. For example, if you place the word "Spreadsheet " (note that this title contains a trailing blank) in front of the brackets, the title of the document is set to "Spreadsheet Untitled-1" for the first new document created, "Spreadsheet Untitled-2" for the second, and so on.

The DoPostMakeViews Method

The DoPostMakeViews method gives your application a chance to do any special view-related setup at a time when you know all view objects for the document have been created and initialized. For example, your document view may contain a field that you cannot easily initialize in a view template resource, so you initialize it in DoPostMakeViews instead.

Saving a Document's Print Information

Each document created by your application can have separate Page Setup print information associated with it. MacApp uses the document's fSavePrintInfo field to determine whether to save the document's print information when writing the document (and whether to read the information when reading the document). By default, the value of this variable is set to TRUE in the constructor for TFileBasedDocument.

If your document has a resource fork, the print information is stored in the resource fork; otherwise, it is stored in the data fork. MacApp writes the print information only if it determines that the information has changed--there is no need to save the information unless it differs from the default for a new document.

If you do not want to save separate page setup information for each document, you set fSavePrintInfo to FALSE in your document's initialization method (IYourDocument), after calling IFileBasedDocument.