A Document is a Container of Data Identified by Name

A document owns and manages data that is in memory when the document is opened and, when saved, is written to a disk file under a user-assigned name. It displays that data in one or more windows and makes it available for editing. A document can not only read and write its data, it can perform other operations on the data, such as print, revert, and undo. The document data can be of any type, and can indeed be of multiple types, but those types must be formally specified. In the document architecture, an NSDocument object represents a document.

The Objects in a Document-Based Application Have Hierarchical Relationships

Three classes are part of the document architecture: NSDocument, NSDocumentController, and NSWindowController. Objects of these classes divide and coordinate the work of creating, saving, opening, and managing the documents of an application. They are arranged in a tiered one-to-many relationship. An NSDocumentController object (of which there is only one per application) creates and manages one or more NSDocument objects. An NSDocument object, in turn, creates and manages one or more NSWindowController objects.

The objects have distinct roles and responsibilities in a document-based application:

• The NSDocumentController object takes the initial steps in creating and opening documents, and once they’re open, tracks and manages them. It also manages the Open Recent menu. The NSDocumentController instance responds automatically to application events such as application launch, application termination, system shutdown, and the opening or printing of documents from the Finder. In the MVC design pattern, an NSDocumentController object is a coordinating controller.

  You typically don’t subclass NSDocumentController. The Xcode project template for document-based applications gives you a ready-made instance of the class as the File’s Owner of the main nib file.

• An NSDocument object’s main role is to represent, manipulate, store, and load the persistent data associated with a document. You specify in the application’s information property list the types of documents that the application can read and write. By default, your custom NSDocument object knows how to run and manage the Save panel and the Page Layout panel. When fully implemented, the object can respond to requests to save, open, and revert documents; it can also track its edited status, print document data, and perform undo and redo operations. In the MVC design pattern, NSDocument plays a hybrid role, that of model-controller.

  You must create a custom subclass of NSDocument. The Xcode project template for document-based applications provides partially defined interface and implementation files for the subclass. Comments in the implementation file give you suggestions for overriding NSDocument methods.

• An NSWindowController object manages one window associated with a document, which is usually stored in a nib file. If a document has multiple windows, each window has its own window controller. Each window controller is responsible for closing windows after ensuring that data is saved. In the MVC design pattern, an NSWindowController object is a view-controller.

  Creating a custom subclass of NSWindowController is optional; you may want to extend the class to load nib files differently, perform special setup tasks, or customize the titles of windows.

The Document Architecture Supports the Automated Application Model

At regular intervals the NSDocument class autosaves documents in place. It overwrites the document file completely by performing a safe save (that is, writing the data to a temporary file, then replacing the current file with that). If a document is untitled—in other words, the user hasn’t saved it under an assigned name in the file system—NSDocument autosaves it in ~/Library/Autosave Information.