Class

NSDocumentController

An object that manages an app's documents.

Declaration

@interface NSDocumentController : NSObject

Overview

As the first-responder target of New and Open menu commands, NSDocumentController creates and opens documents and tracks them throughout a session of the app. When opening documents, a document controller runs and manages the modal Open panel. NSDocumentController objects also maintain and manage the mappings of document types, extensions, and NSDocument subclasses as specified in the CFBundleDocumentTypes property loaded from the information property list (Info.plist).

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 filename or window, and find out about a document’s extension, type, display name, and document class.

In some situations, it is worthwhile to subclass NSDocumentController in non-NSDocument-based apps to get some of its features. For example, the NSDocumentController management of the Open Recent menu is useful in apps that don’t use subclasses of NSDocument.

Topics

Obtaining the Shared Document Controller

sharedDocumentController

Returns the shared NSDocumentController instance.

Initializing a New NSDocumentController

- init

This method is the designated initializer for NSDocumentController.

- initWithCoder:

This method initializes a new NSDocumentController from the coder.

Creating and Opening Documents

- documentForURL:

Returns, for a given URL, the open document whose file or file package is located by the URL, or nil if there is no such open document.

- duplicateDocumentWithContentsOfURL:copying:displayName:error:

Creates a new document by reading the contents for the document from another URL, presents its user interface, and returns the document if successful.

- openDocumentWithContentsOfURL:display:completionHandler:

Opens a document located by a URL, optionally presents its user interface, and calls the passed-in completion handler.

- openUntitledDocumentAndDisplay:error:

Creates a new untitled document, presents its user interface if displayDocument is YES, and returns the document if successful.

- makeDocumentForURL:withContentsOfURL:ofType:error:

Instantiates a document located by a URL, of a specified type, but by reading the contents for the document from another URL, and returns it if successful.

- makeDocumentWithContentsOfURL:ofType:error:

Instantiates a document located by a URL, of a specified type, and returns it if successful.

- makeUntitledDocumentOfType:error:

Instantiates a new untitled document of the specified type and returns it if successful.

- reopenDocumentForURL:withContentsOfURL:display:completionHandler:

Reopens a document, optionally located by a URL, by reading the contents for the document from another URL, optionally presents its user interface, and calls the passed-in completion handler.

Managing Documents

documents

The document objects managed by the receiver.

- addDocument:

Adds the given document to the list of open documents.

currentDocument

The document object associated with the main window.

- documentForWindow:

Returns the document object whose window controller owns a specified window.

hasEditedDocuments

A Boolean value indicating whether the receiver has any documents with unsaved changes.

- removeDocument:

Removes the given document from the list of open documents.

Managing Document Types

documentClassNames

An array of strings representing the custom document classes supported by this app.

defaultType

Returns the name of the document type that should be used when creating new documents.

- documentClassForType:

Returns the NSDocument subclass associated with a given document type.

- displayNameForType:

Returns the descriptive name for the specified document type, which is used in the File Format pop-up menu of the Save As dialog.

- typeForContentsOfURL:error:

Returns, for a specified URL, the document type identifier to use when opening the document at that location, if successful.

Autosaving

autosavingDelay

The time interval (in seconds) for periodic autosaving.

Closing Documents

- closeAllDocumentsWithDelegate:didCloseAllSelector:contextInfo:

Iterates through all the open documents and tries to close them one by one using the specified delegate.

- reviewUnsavedDocumentsWithAlertTitle:cancellable:delegate:didReviewAllSelector:contextInfo:

Displays an alert asking if the user wants to review unsaved documents, quit regardless of unsaved documents, or cancel the save operation.

Responding to Action Messages

- newDocument:

An action method called by the New menu command, this method creates a new NSDocument object and adds it to the list of such objects managed by the document controller.

- openDocument:

An action method called by the Open menu command, it runs the modal Open panel and, based on the selected filenames, creates one or more NSDocument objects from the contents of the files.

- saveAllDocuments:

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

Managing the Open Dialog

- beginOpenPanelWithCompletionHandler:

Presents an Open dialog and delivers the results to a completion handler as an array of URLs for the chosen files (or nil).

- beginOpenPanel:forTypes:completionHandler:

Presents a nonmodal Open dialog that displays files that can be opened based on a list of UTIs.

- runModalOpenPanel:forTypes:

Presents a modal Open dialog and limits selection to specific file types.

currentDirectory

The directory path to be used as the starting point in the Open panel.

- URLsFromRunningOpenPanel

An array of URLs corresponding to the files selected in a running open panel.

Managing the Open Recent Menu

maximumRecentDocumentCount

The maximum number of items that may be presented in the standard Open Recent menu.

- clearRecentDocuments:

Empties the recent documents list for the application.

- noteNewRecentDocumentURL:

Adds or replaces an Open Recent menu item corresponding to the data located by the URL.

- noteNewRecentDocument:

Adds or replaces an Open Recent menu item corresponding to the document.

recentDocumentURLs

The list of recent-document URLs.

Validating User Interface Items

- validateUserInterfaceItem:

Returns a Boolean value that indicates whether a given user interface item should be enabled.

Handling Errors

- presentError:

Presents an error alert to the user as a modal panel.

- presentError:modalForWindow:delegate:didPresentSelector:contextInfo:

Presents an error alert to the user as a modal panel.

- willPresentError:

Indicates an error condition and provides the opportunity to return the same or a different error.

Deprecated Methods

- documentForFileName:

Returns the document object for the file in which the document data is stored.

Deprecated
- fileExtensionsFromType:

Returns the allowable file extensions for the given document type.

Deprecated
- fileNamesFromRunningOpenPanel

Returns a selection of files chosen by the user in the Open panel.

Deprecated
- makeUntitledDocumentOfType:

Creates and returns a document object for document type.

Deprecated
- makeDocumentWithContentsOfURL:ofType:

Creates and returns a document object for the given document type from the contents of a given URL.

Deprecated
- makeDocumentWithContentsOfFile:ofType:

Creates and returns a document object of a given document type from the contents of a file.

Deprecated
- openDocumentWithContentsOfFile:display:

Returns a document object created from the contents of a given file and optionally displays it.

Deprecated
- openDocumentWithContentsOfURL:display:

Returns a document object created from the contents of a given URL and optionally displays it.

Deprecated
- openDocumentWithContentsOfURL:display:error:

Opens a document located by the given URL presents its user interface if requested, and returns the document if successful.

Deprecated
- openUntitledDocumentOfType:display:

Returns a document object instantiated from the subclass of the given document type and optionally displays it.

Deprecated
- reopenDocumentForURL:withContentsOfURL:error:

Reopens an autosaved document located by a URL, by reading the contents for the document from another URL, presents its user interface, and returns YES if successful.

Deprecated
- setShouldCreateUI:

Sets whether the window controllers of a document should be created when the document is created.

Deprecated
- shouldCreateUI

Returns a Boolean value that indicates whether the window controllers of a document should be created when the document is created.

Deprecated
- typeFromFileExtension:

Returns the document type associated with files having extension fileExtensionOrHFSFileType.

Deprecated

Relationships

Inherits From

See Also

Documents

Developing a Document-Based App

Write an app that creates, manages, edits, and saves text documents.

NSPersistentDocument

A document object that can integrate with Core Data.

NSDocument

An abstract class that defines the interface for macOS documents.