---

Document-Based Application Architecture

A document-based application is one of the more common types of applications. It provides a framework for generating identically contained but uniquely composed sets of data that can be stored in files. Word processors and spreadsheet applications are two examples of document-based applications. Document-based applications do the following things:

• Create new documents.

• Open existing documents that are stored in files.

• Save documents under user-designated names and locations.

• Revert to saved documents.

• Close documents (usually after prompting the user to save edited documents).

• Print documents and allow the page layout to be modified.

• Represent data of different types internally.

• Monitor and set the document’s edited status and validate menu items.

• Manage document windows, including setting the window titles.

• Handle application and window delegation methods (such as when the application terminates).

Contents:

The Major Classes
What Is a Document?

The Major Classes

Three Application Kit classes provide an architecture for document-based applications, called the document architecture, that simplifies the work developers must do to implement the features listed above. These classes are NSDocument, NSWindowController, and NSDocumentController.

Objects of these classes divide and orchestrate the work of creating, saving, opening, and managing the documents of an application. They are arranged in a tiered one-to-many relationship, as depicted in Figure 1. An application can have only one NSDocumentController, which creates and manages one or more NSDocument objects (one for each New or Open operation). In turn, an NSDocument object creates and manages one or more NSWindowController objects, one for each of the windows displayed for a document. In addition, some of these objects have responsibilities analogous to NSApplication and NSWindow delegates, such as approving major events like closing and quitting.

What Is a Document?

Conceptually, a document is a container for a body of information identified by a name under which it is stored in a disk file. In this sense, however, the document is not the same as the file but is an object in memory that owns and manages the document data. In the context of the Application Kit, a document is an instance of a custom NSDocument subclass that knows how to represent internally, in one or more formats, persistent data that is displayed in windows. A document can read that data from a file and write it to a file. It is also the first-responder target for many menu commands related to documents, such as Save, Revert, and Print. A document manages its window’s edited status and is set up to perform undo and redo operations. When a window is closing, the Application Kit first asks the document, before it asks the window delegate, to approve the closing.

To create a useful NSDocument subclass, you must override some methods, and you might want to override others. The NSDocument class itself knows how to handle document data as undifferentiated lumps; although it understands that these lumps are typed, it knows nothing about particular types. In their overrides of the data-based reading and writing methods, subclasses must add the knowledge of particular types and how data of the document’s native type is structured internally. Subclasses are also responsible for the creation of the window controllers that manage document windows and for the implementation of undo and redo. The NSDocument class takes care of much of the rest, including generally managing the state of the document.

---