Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Objective-C

Table of Contents

NSDocumentController


Inherits from:
NSObject
Conforms to:
NSCoding
NSObject (NSObject)
Declared in:
AppKit/NSDocumentController.h




Class Description


An NSDocumentController object manages an application's documents. As the first-responder target of New and Open menu commands, it creates and opens documents and tracks them throughout a session of the application.When opening documents, an NSDocumentController runs and manages the modal Open panel. As the application delegate, it saves and closes documents when applications are terminated and it responds to NSWorkspace methods when documents are opened or printed from the workspace. NSDocumentControllers also maintain and manage the mappings of document types, extensions, and NSDocument subclasses as specified in the NSTypes property loaded from the custom info property list (CustomInfo.plist). One instance of NSDocumentController is shared among processes.

You can use various NSDocumentController methods to get a list of the current documents, get the current document (which is the document whose window is currently key), get documents based on a given file name or window, and to find out about a document's extension, type, display name, and document class.

A document-based application can use the default NSDocumentController instance provided by the Application Kit, because this instance not only creates and manages documents, but acts as application controller. Typically, however, applications will require their own custom subclasses of NSDocumentController to implement behavior not provided by default, such as loading About panels and managing user preferences.

For more on the architecture of document-based applications, and the procedure for implementing, see the concepts "Document-Based Application Architecture" and "Implementing a Document-Based Application" , currently in the NSDocument class description.




Method Types


Obtaining the shared instance
+ sharedDocumentController
Initializing a new NSDocumentController
- init
Creating and opening documents
- makeDocumentWithContentsOfFile:ofType:
- makeDocumentWithContentsOfURL:ofType:
- makeUntitledDocumentOfType:
- openDocumentWithContentsOfFile:display:
- openDocumentWithContentsOfURL:
- openUntitledDocumentOfType:display:
- setShouldCreateUI:
- shouldCreateUI
Managing the Open panel
- runModalOpenPanel:forTypes:
- fileNamesFromRunningOpenPanel
- currentDirectory
- URLsFromRunningOpenPanel
Closing documents
- closeAllDocuments
- reviewUnsavedDocumentsWithAlertTitle:cancellable:
Responding to action messages
- newDocument:
- openDocument:
- saveAllDocuments:
Managing documents
- documents
- addDocument:
- clearRecentDocuments:
- currentDocument
- documentClassForType:
- documentForFileName:
- documentForWindow:
- hasEditedDocuments
- noteNewRecentDocumentURL:
- recentDocumentURLs
- removeDocument:
Managing document types
- displayNameForType:
- fileExtensionsFromType:
- typeFromFileExtension:
Validating menu items
- validateMenuItem:


Class Methods



sharedDocumentController

+ (id)sharedDocumentController

Returns the shared NSDocumentController instance. If one doesn't exist yet, it is created. Initialization reads in the document types from the NSTypes property list (in CustomInfo.plist), registers the instance for NSWorkspaceWillPowerOffNotifications, and turns on the flag indicating that document user interfaces should be visible. You should always obtain your application's NSDocumentController using this method.

See Also: - setShouldCreateUI:




Instance Methods



addDocument:

- (void)addDocument:(NSDocument *)document

Adds document to the list of open documents. The open... methods automatically call addDocument:. This method is mostly provided for subclassers that want to know when documents arrive.

clearRecentDocuments:

- (IBAction)clearRecentDocuments:(id)sender

Empties the recent documents list for the application. This is the action for the Clear Menu command, but it can be invoked directly if necessary.

closeAllDocuments

- (BOOL)closeAllDocuments

Attempts to close all documents owned by the receiver and returns whether all documents were closed. It does not ask users whether they want to save documents. This method is invoked in reviewUnsavedDocumentsWithAlertTitle:cancellable: when users decide to discard all changes.

currentDirectory

- (NSString *)currentDirectory

Returns the directory path to be used as the starting point in the Open panel. The first valid directory from the following list is returned:

See Also: - documentForFileName:



currentDocument

- (id)currentDocument

Returns the NSDocument object associated with the main window.

See Also: - documentForFileName:, - documentForWindow:, - documents



displayNameForType:

- (NSString *)displayNameForType:(NSString *)docType

Returns the descriptive name for the document type (docType), which is often part of the document's window title. This returned value is associated with the NSTypeName key in the NSType property list.If there is no such value, docType is returned.

See Also: - fileExtensionsFromType:, - typeFromFileExtension:



documentClassForType:

- (Class)documentClassForType:(NSString *)docType

Returns the NSDocument subclass associated with document type docType. The document type must be one the document can read. If the class cannot be found, returns nil.

See Also: - displayNameForType:, - fileExtensionsFromType:, - typeFromFileExtension:



documentForFileName:

- (id)documentForFileName:(NSString *)fileName

Returns the NSDocument object for the file in which the document data is stored. The fileName argument is a fully qualified path in the file system. Returns nil if no document can be found.

See Also: - documentForWindow:, - documents



documentForWindow:

- (id)documentForWindow:(NSWindow *)window

Returns the NSDocument object whose window controller owns window. Returns nil if window is nil, if window has no window controller, or if the window controller does not have an association with an NSDocument.

See Also: - currentDocument, - documentForFileName:, - documents



documents

- (NSArray *)documents

Returns the NSDocument objects managed by the receiver. If there are currently no documents, returns an empty NSArray.

See Also: - currentDocument, - documentForFileName:, - documentForWindow:



fileExtensionsFromType:

- (NSArray *)fileExtensionsFromType:(NSString *)docType

Returns the allowable file extensions (as NSString objects) for document type docType. The first string in the returned NSArray is typically the most common extension.

See Also: - displayNameForType:, - typeFromFileExtension:



fileNamesFromRunningOpenPanel

- (NSArray *)fileNamesFromRunningOpenPanel

Returns a selection of files chosen by the user in the Open panel. Each file in the returned NSArray is a fully qualified path to the file's location in the file system. This method is invoked by openDocument: and it invokes runModalOpenPanel:forTypes: after initializing the Open panel (which includes getting the starting directory with currentDirectory). Returns nil if the user cancels the Open panel or makes no selection.

hasEditedDocuments

- (BOOL)hasEditedDocuments

Returns whether the receiver has any documents with unsaved changes.

See Also: - documents



init

- (id)init

This is the designated initializer for the NSDocumentController. The first instance of NSDocumentController or any of its subclasses which is created becomes the shared instance.

makeDocumentWithContentsOfFile:ofType:

- (id)makeDocumentWithContentsOfFile:(NSString *)fileName ofType:(NSString *)docType

Creates and returns an NSDocument object for document type docType from the contents of the file fileName, which must be a fully qualified path. The returned object is not retained. Returns nil if the NSDocument subclass for docType couldn't be determined or if the object couldn't be created. This method invokes NSDocument's initWithContentsOfFile:ofType: and is invoked by openDocumentWithContentsOfFile:display:.

See Also: - makeUntitledDocumentOfType:, - openDocument:



makeDocumentWithContentsOfURL:ofType:

- (id)makeDocumentWithContentsOfURL:(NSURL *)anURL ofType:(NSString *)docType

Creates and returns an NSDocument object for document type docType from the contents of anURL. The returned object is not retained. Returns nil if the NSDocument subclass for docType couldn't be determined or if the object couldn't be created. This method invokes NSDocument's initWithContentsOfURL:ofType: and is invoked by openDocumentWithContentsOfURL:.

See Also: - makeUntitledDocumentOfType:, - openDocument:



makeUntitledDocumentOfType:

- (id)makeUntitledDocumentOfType:(NSString *)type

Creates and returns an NSDocument object for document type docType. The returned object is not retained. Returns nil if the NSDocument subclass for docType couldn't be determined or if the object couldn't be created. This method invokes NSDocument's init and is invoked by openUntitledDocumentOfType:display:.

See Also: - makeDocumentWithContentsOfFile:ofType:, - newDocument:



newDocument:

- (void)newDocument:(id)sender

An action method invoked the New menu command, it creates a new NSDocument object and adds it to the list of such objects managed by the receiver. It invokes openUntitledDocumentOfType:display: with the document type (first argument) being the first one specified in the NSType property (defined in CustomInfo.plist); the document type determines the NSDocument subclass used to instantiate the document object.

See Also: - openDocument:



noteNewRecentDocumentURL:

- (void)noteNewRecentDocumentURL:(NSURL *)anURL

This method should be called by non NSDocument-based apps when they open/save documents. NSDocument automatically calls this method when appropriate for NSDocument-based apps. You can override this in an NSDocument-based application to prevent certain kinds of documents from getting into the list (but you have to identify them by their URL).

openDocument:

- (IBAction)openDocument:(id)sender

An action method invoked the Open menu command, it runs the modal Open panel and, based on the selected filenames, creates one or more NSDocument object from the contents of the files; it adds these objects to the list of NSDocument objects managed by the receiver. This method invokes openDocumentWithContentsOfFile:display:, which actually creates the NSDocument objects.

See Also: - fileNamesFromRunningOpenPanel, - newDocument:



openDocumentWithContentsOfFile:display:

- (id)openDocumentWithContentsOfFile:(NSString *)fileName display:(BOOL)flag

Returns an NSDocument object created from the contents of the file fileName (an absolute path) and displays it if flag is YES. The returned object is not retained, but is added to the receiver's list of managed documents. Returns nil if the object could not be created, typically because fileName does not point to a valid file or because there is no NSDocument subclass for the document type (as indicated by the file extension). Even if flag is YES, the document is not displayed if shouldCreateUI returns NO. This method invokes makeDocumentWithContentsOfFile:ofType: to obtain the created NSDocument object.

See Also: - openDocument:, - openUntitledDocumentOfType:display:, - setShouldCreateUI:



openDocumentWithContentsOfURL:

- (id)openDocumentWithContentsOfURL:(NSURL *)anURL display:(BOOL)flag

Returns an NSDocument object created from the contents of anURL and displays it if flag is YES. The returned object is not retained, but is added to the receiver's list of managed documents. Returns nil if the object could not be created, typically because anURL does not point to a valid location or because there is no NSDocument subclass for the document type. Even if flag is YES, the document is not displayed if shouldCreateUI returns NO. This method invokes makeDocumentWithContentsOfURL:ofType: to obtain the created NSDocument object.

See Also: - openDocument:, - openUntitledDocumentOfType:display:, - setShouldCreateUI:



openUntitledDocumentOfType:display:

- (id)openUntitledDocumentOfType:(NSString *)docType display:(BOOL)display

Returns an NSDocument object instantiated from the NSDocument subclass required by document type docType and displays it if flag is YES. The returned object is not retained, but is added to the receiver's list of managed documents. Returns nil if the object could not be created, typically because no NSDocument subclass could be found for docType. Even if flag is YES, the document is not displayed if shouldCreateUI returns NO. This method invokes makeUntitledDocumentOfType: to obtain the created NSDocument object.

See Also: - newDocument:, - openDocumentWithContentsOfFile:display:, - setShouldCreateUI:



recentDocumentURLs

- (NSArray *)recentDocumentURLs

Returns the list of recent document URLs. This is not a good method to override since the internals of NSDocumentController do not generally use it.

removeDocument:

- (void)removeDocument:(NSDocument *)document

Removes document from the list of open documents. A document will automatically call removeDocument: when it closes. This method is mostly provided for subclassers that want to know when documents close.

reviewUnsavedDocumentsWithAlertTitle:cancellable:

- (BOOL)reviewUnsavedDocumentsWithAlertTitle:(NSString *)title cancellable:(BOOL)flag

Displays an attention panel (a dialog) asking users if they want to review unsaved documents, quit regardless of unsaved documents, or (if flag is YES) if they want to cancel the impending save-and-terminate operation. Returns YES if the application is to quit and NO if otherwise (used only when the application is terminating). If the user selects the Review Unsaved option, closeAllDocuments is invoked. This method is invoked when users choose the Quit menu command and when the computer power is being turned off (in which case, flag is NO).

runModalOpenPanel:forTypes:

- (int)runModalOpenPanel:(NSOpenPanel *)openPanel forTypes:(NSArray *)extensions

Invokes NSOpenPanel's runModalForTypes: passing the file extensions associated with a document type. This method is invoked by the fileNamesFromRunningOpenPanel method.

saveAllDocuments:

- (IBAction)saveAllDocuments:(id)sender

As the action method invoked by the Save All command, saves all open documents of the application that need to be saved.

See Also: - saveDocument: (NSDocument)



setShouldCreateUI:

- (void)setShouldCreateUI:(BOOL)flag

Sets whether the window controllers (NSWindowControllers) of a document should be created when the document is created. When a window controller is created, it loads the nib file containing the window it manages. Often flag is set to NO for scripting or searching operations involving the document's data.

See Also: - shouldCreateUI



shouldCreateUI

- (BOOL)shouldCreateUI

Returns whether the window controllers (NSWindowControllers) of a document should be created when the document is created.

See Also: - setShouldCreateUI:



typeFromFileExtension:

- (NSString *)typeFromFileExtension:(NSString *)fileExtension

Returns the document type associated with files having extension fileExtension.

See Also: - displayNameForType:, - fileExtensionsFromType:



URLsFromRunningOpenPanel

- (NSArray *)URLsFromRunningOpenPanel

Description forthcoming.

validateMenuItem:

- (BOOL)validateMenuItem:(NSMenuItem *)anItem

Validates menu item anItem, returning YES if it should be enabled, NO otherwise. As implemented, if anItem is the Save All menu item, returns YES if there are any edited documents. Subclasses can override this method to perform additional validations.


Table of Contents