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.
Last updated: 2010-03-24