---

Creating Multiple-Document-Type Applications

The document architecture provides support for applications that handle multiple types of documents, each type using its own subclass of NSDocument. For example, AppleWorks allows you to create text documents, spreadsheets, and other types of documents, all in a single application. Such different document types each require a different user interface encapsulated in a unique NSDocument subclass. To integrate multiple subclasses into your document-based application, you can configure your nib files, Info.plist file, and document controller as described in this article.

You create a document-based application in Xcode by selecting the Cocoa Document-based Application template in the New Project panel. Xcode provides an NSDocument subclass with a window already configured in a nib file to display the document. If you create additional nib files and additional NSDocument subclasses, however, you must configure them manually.

To create a new NSDocument subclass, create the class interface and implementation of primitive reading and writing methods as described in “Creating a Subclass of NSDocument.”

Use Interface Builder to design the user interface for your document, which is stored in the nib file for the document window. Implement the windowNibName method in your NSDocument subclass to return the name of the nib file.

In a new window nib file created in Interface Builder, the file's owner is not automatically configured to the the NSDocument subclass, but is instead set to NSObject. So, you must configure the file's owner of the nib file to be your NSDocument subclass or, if you subclass NSWindowController to manage your user interface, configure the file's owner of the nib file to be your NSWindowController subclass. Then you must set the window outlet of the file's owner object to be your window. Otherwise, the window won't display when you create a new document instance from your subclass. Additionally, set the window's delegate outlet to the file's owner.

You also must configure the Info.plist file to describe your NSDocument subclass under the CFBundleDocumentTypes key, as described in “Storing Document Types Information in the Application's Property List.”

If your multiple-document-type application opens only existing documents, you can use the default NSDocumentController instance that is automatically created by the Application Kit, because the document type is determined from the file being opened. However, if your application creates new documents, it needs to choose the correct type.

The NSDocumentController action method newDocument: creates a new document of the first type listed in the application’s array of document types (as configured in the Info.plist file). But this does not work for applications that want to support several distinct types of document. If your application cannot determine which type to create depending on circumstances, you must provide a user interface allowing the user to choose which type of document to create.

You can create your own new actions, either in your application’s delegate or in an NSDocumentController subclass. You could create several action methods and have several different New menu items, or you could have one action that asks the user to pick a document type before creating a new one.

Once the user selects a type, your action method can use the NSDocumentController method makeUntitledDocumentOfType:error: to create a document of the correct type. After creating the document, your method should add it to the document controller's list of documents, and it should send the document makeWindowControllers and showWindows messages, as described in “Message Flow in the Document Architecture.”

Alternatively, if you subclass NSDocumentController, you can override the defaultType method to determine the document type and return it, when the user chooses New from the File menu.

---