# NSDocumentController

Carl.Lindberg@hbo.com

The document controller class

1999 Free Software Foundation, Inc.
Software documentation for the NSDocumentController class
AppKit/NSDocumentController.h

NSDocumentController is a class that controls a set of NSDocuments for an application. As an application delegate, it responds to the typical File Menu commands for opening and creating new documents, and making sure all documents have been saved when an application quits. It also registers itself for the NSWorkspaceWillPowerOffNotification. Note that NSDocumentController isn't truly the application delegate, but it works in a similar way. You can still have your own application delegate - but beware, if it responds to the same methods as NSDocumentController, your delegate methods will get called, not the NSDocumentController's.

NSDocumentController also manages document types and the related NSDocument subclasses that handle them. This information comes from the custom info property list ({ApplicationName}Info.plist) loaded when NSDocumentController is initialized. The property list contains an array of dictionarys with the key NSTypes. Each dictionary contains a set of keys:

NSDocumentClass - The name of the subclass
NSName - Short name of the document type
NSHumanReadableName - Longer document type name
NSUnixExtensions - Array of strings
NSDOSExtensions - Array of strings
NSIcon - Icon name for these documents
NSRole - Viewer or Editor

You can use NSDocumentController to get a list of all open documents, the current document (The one whose window is Key) and other information about these documents. It also remembers the most recently opened documents (through the user default key NSRecentDocuments)..

You can subclass NSDocumentController to customize the behavior of certain aspects of the class, but it is very rare that you would need to do this.

sharedDocumentController
Returns the shared instance of the document controller class. You should always use this method to get the NSDocumentController.
URLsFromRunningOpenPanel
Uses -runModalOpenPanel:forTypes: to allow the user to select files to open (after initializing the NSOpenPanel). Returns the list of files as URLs that the user has selected.
addDocument:
document
Description forthcoming.
clearRecentDocuments:
sender
Description forthcoming.
closeAllDocuments
Iterates through all the open documents and asks each one in turn if it can close using [NSDocument -canCloseDocument]. If the document returns `YES`, then it is closed.
closeAllDocumentsWithDelegate:
delegate
didCloseAllSelector:
didAllCloseSelector
contextInfo:
contextInfo
Description forthcoming.
currentDirectory
Returns the current directory. This method first checks if there is a current document using the -currentDocument method. If this returns a document and the document has a filename, this method returns the directory this file is located in. Otherwise it returns the directory of the most recently opened document or the user's home directory if no document has been opened before.
currentDocument
Returns the document whose window is the main window
displayNameForType:
type
Description forthcoming.
documentClassForType:
type
Description forthcoming.
documentForFileName:
fileName
Returns the NSDocument class that controls the document with the name fileName.
documentForWindow:
window
Returns the NSDocument class that controls window
documents
Returns an array of all open documents
fileExtensionsFromType:
type
Description forthcoming.
fileNamesFromRunningOpenPanel
Uses -runModalOpenPanel:forTypes: to allow the user to select files to open (after initializing the NSOpenPanel). Returns the list of files that the user has selected.
hasEditedDocuments
Returns `YES` if any documents are "dirty", e.g. changes have been made to the document that have not been saved to the disk
makeDocumentWithContentsOfFile:
fileName
ofType:
type
Description forthcoming.
makeDocumentWithContentsOfURL:
url
ofType:
type
Description forthcoming.
makeUntitledDocumentOfType:
type
Description forthcoming.
newDocument:
sender
Description forthcoming.
noteNewRecentDocument:
aDocument
Description forthcoming.
noteNewRecentDocumentURL:
anURL
Description forthcoming.
openDocument:
sender
Description forthcoming.
openDocumentWithContentsOfFile:
fileName
display:
display
Creates an NSDocument object from the data at the absolute path given in fileName. Causes the document to be displayed if display is `YES`, unless the -shouldCreateUI method returns `NO`.
openDocumentWithContentsOfURL:
url
display:
display
Creates an NSDocument object from the data at the supplied url.
Causes the document to be displayed if display is `YES`, unless the -shouldCreateUI method returns `NO`.
openUntitledDocumentOfType:
type
display:
display
Description forthcoming.
recentDocumentURLs
Description forthcoming.
removeDocument:
document
Description forthcoming.
reviewUnsavedDocumentsWithAlertTitle:
title
cancellable:
cancellable
If there are any unsaved documents, this method displays an alert panel asking if the user wants to review the unsaved documents. If the user agrees to review the documents, this method calls -closeAllDocuments to close each document (prompting to save a document if it is dirty). If cancellable is `YES`, then the user is not allowed to cancel this request, otherwise this method will return `NO` if the user presses the Cancel button. Otherwise returns `YES` after all documents have been closed (or if there are no unsaved documents.)
reviewUnsavedDocumentsWithAlertTitle:
title
cancellable:
cancellable
delegate:
delegate
didReviewAllSelector:
didReviewAllSelector
contextInfo:
contextInfo
Description forthcoming.
runModalOpenPanel:
openPanel
forTypes:
openableFileExtensions
Invokes [NSOpenPanel -runModalForTypes:] with the NSOpenPanel object openPanel, and passes the openableFileExtensions file types
saveAllDocuments:
sender
Description forthcoming.
setShouldCreateUI:
flag
Description forthcoming.
shouldCreateUI
Description forthcoming.
typeFromFileExtension:
fileExtension
Description forthcoming.
validateMenuItem:
anItem
Description forthcoming.
validateUserInterfaceItem:
anItem
Description forthcoming.