The primary job of a document object—an instance of an NSDocument subclass that you provide as part of your application—is to represent, manipulate, store, and load the data associated with a document. Based on the document types it claims to understand (as specified in the application’s info property list), a document object must be prepared to do the following things:

With the assistance of its window controllers, a document-object instance manages the display and capture of the data in its windows. The document-object instance associated with the key window is made the first responder to action messages indicating that a user wants to save, print, revert, or close a document. A fully implemented document object knows how to track its edited status, print document data, and perform undo and redo operations. As you’ll see in the examples in this and later chapters, these behaviors aren’t provided completely by default, but the NSDocument class goes a long way to assist you in implementing each.

For edited-status tracking, the NSDocument class provides an API for updating a document change counter. For undo/redo operations, NSDocument creates an NSUndoManager when one is requested, which responds appropriately to the Edit → Undo and Edit → Redo menu commands, updating the change counter when undo and redo operations are invoked.

Every application that takes advantage of the AppKit’s document-based application architecture must create at least one subclass of NSDocument. The architecture requires that you override some methods of the NSDocument class. These methods must be implemented:

The primary job of an application’s document-controller object (NSDocumentController ) is to create and open documents, as well as to track and manage these documents. The document controller maintains a list of document objects and tracks the current document (the document whose window is currently key). It is hardwired to respond appropriately to certain application events, such as when the application starts up, when it terminates, when the system powers off, and when documents are opened or printed from the Finder. For example, when a user chooses New from the File menu, the document controller does the following things:

When the user chooses Open from the File menu, the document controller does the following things:

When the user chooses Save or Save As from the File menu, the document controller does the following things:

In a document-based application, many of the application’s menu items are already connected to the document controller. These methods are implemented by the NSDocumentController class and are listed in Table 10-1.

newDocument:

openDocument:

saveDocument:

saveDocumentAs:

saveDocumentTo:

saveAllDocuments:

closeDocument:

revertDocumentToSaved:

printDocument:

runPageLayout:

The default document-controller behavior provided by the NSDocumentController class is usually sufficient for most situations; you shouldn’t need to subclass it unless you need to provide alternative functionality for the methods listed earlier.

A window controller, an instance of the NSWindowController class, manages one window associated with a document. If a document has multiple open windows, each window has its own instance of NSWindowController. For example, a document might have a main data-entry window and a window that lists records for selection. Each window would have its own window controller. When a document has multiple window controllers, only one of them is considered the primary window controller. When the primary window is closed, the document and all other windows are closed.

When requested by the NSDocument class, a window controller loads the nib file containing a window and displays it. The window controller assumes responsibility for managing the nib file.

When a document is closed, the window controller is responsible for properly closing windows, as well as freeing any top-level objects instantiated by the nib file. This includes the window itself and any additional objects added to the nib.

Most of the time, you can use the default window controller provided by the AppKit. Some applications may want to subclass NSWindowController to move the user-interface-specific logic out of the NSDocument subclass. The Sketch sample application in /Developer/Examples/AppKit uses this technique. Another situation that would make subclassing desirable is if you wanted to support multiple views onto a document; for example, in a 3D modeling application you would want to present various views of the model.

The multiple-document architecture automates much of the memory management for documents and their associated window and document controllers. One of the document controller’s responsibilities is to ensure that a document is open and using memory only if it has a window open on the screen. When a window closes, it tells its window controller that it is closing. The window controller, in turn, tells its document that it is closing. The document notes that the window controller is closing, removes the window controller from its list of window controllers, and releases it. As this is the only place the window controller is retained, the window controller gets released and deallocated as a result.

Project Builder provides a template named "Document-based Application” to expedite the development of these kinds of applications. This project type provides the following things:

To get started working on building our text editor:

Double-click on the MyDocument.nib file (located in the Resources folder of the Groups & Files panel in Project Builder), so you can examine the interface in Interface Builder. The nib file is quite simple, as shown in Figure 10-3. There is only a single window with a default text string.

If you select the File’s Owner instance and bring up the Inspector (Tools → Show Info, or Shift-

-I), you’ll notice in the Attributes pane that File’s Owner is set to correspond to an instance of MyDocument. Also, in the Connections pane, you’ll see an outlet with a connection to the window.

Switch back to Project Builder, and double-click on the MainMenu.nib file to open it in Interface Builder. Click through the menu items with the Connections inspector open, as shown in Figure 10-4, and notice how many of the application’s menu items have already been connected to appropriate first responder action methods. These methods are implemented by the application’s document controller (an NSDocumentController instance).

Figure 10-3. MyDocument.nib in Interface Builder

Figure 10-4. Examining prebuilt connections

Return to Project Builder, and open MyDocument.m, located in the Classes folder of the Groups & Files pane. Examine the skeletal implementation of this NSDocument subclass, and you’ll see that the four methods that must be implemented already have a skeletal implementation, as shown in Example 10-1.

#import "MyDocument.h"

@implementation MyDocument

- (id)init
{
    [super init];
    if (self) {
    
        // Add your subclass-specific initialization here.
        // If an error occurs here, send a [self dealloc] message and return nil.
    
    }
    return self;
}

- (NSString *)windowNibName
{
    // Override returning the nib file name of the document
    // If you need to use a subclass of NSWindowController or if your 
    // document supports multiple NSWindowControllers, you should remove
    // this method and override -makeWindowControllers instead.
    return @"MyDocument";
}

- (void)windowControllerDidLoadNib:(NSWindowController *) aController
{
    [super windowControllerDidLoadNib:aController];
    // Add any code here that need to be executed once the windowController 
    // has loaded the document's window.
}

- (NSData *)dataRepresentationOfType:(NSString *)aType
{
    // Insert code here to write your document from the given data.
    // You can also choose to override -fileWrapperRepresentationOfType: 
    // or -writeToFile:ofType: instead.
    return nil;
}

- (BOOL)loadDataRepresentation:(NSData *)data ofType:(NSString *)aType
{
    // Insert code here to read your document from the given data.
    // You can also choose to override -loadFileWrapperRepresentation:ofType: 
    // or -readFromFile:ofType: instead.
    return YES;
}

@end

Save the project (File → Save, or

-S), and then build and run the application (Build → Build and Run, or

-R).

Now you can experiment with the document-based application.

Next, we’ll implement the functionality needed to turn this skeleton into a full-blown text editor that allows us to save and open text files.

In this section, you’ll define the look and feel of the application’s document. Just modify the default nib file (created by Project Builder’s template) by adding a text view that will allow the user to view and edit text.

The Applications Settings pane of the target window allows you to create and modify a variety of application-wide properties. Critical values, like the name of the executable and the name of the main Cocoa class, are provided by default. Many of the other properties are important for a full-fledged application, but they can remain unset for this simple example. You’ll learn more about these properties later in the book. For now, don’t worry about them.

Our Simple Text Edit application will handle only one kind of data: text. It’s very simple to modify the application’s info property list to add support for this document type.

These settings allow the document architecture to recognize .txt files as files that can be opened by our application, instructing the system to use an instance of the MyDocument class to open those files. In addition, the system will allow only files saved from a MyDocument instance to have the extension .txt.

Now, we implement the MyDocument class to support reading and writing text data.

Open MyDocument.m. The following steps will fill in the methods of the skeleton source file from Example 10-1. We’ll fill in the stubbed methods in a different order than they appear in the file so that we can have each step build on top of the previous one. In addition, we’ll show the code without the comments—it’s your choice whether to leave them in your application.

Cocoa’s multiple-document architecture, as well as the capabilities built into the NSTextView class, provides the functionality that users expect Cfrom a text editing application. We’ve simply glued these features together by adding just a few lines of code.