An object that manages an app's documents.


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.


Obtaining the Shared Document Controller

class var shared: NSDocumentController

Returns the shared NSDocumentController instance.

Initializing a New NSDocumentController


This method is the designated initializer for NSDocumentController.

Creating and Opening Documents

func document(for: URL)

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.

func duplicateDocument(withContentsOf: URL, copying: Bool, displayName: String?)

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

func openDocument(withContentsOf: URL, display: Bool, completionHandler: (NSDocument?, Bool, Error?) -> Void)

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

func openUntitledDocumentAndDisplay(Bool)

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

func makeDocument(for: URL?, withContentsOf: URL, ofType: String)

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.

func makeDocument(withContentsOf: URL, ofType: String)

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

func makeUntitledDocument(ofType: String)

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

func reopenDocument(for: URL?, withContentsOf: URL, display: Bool, completionHandler: (NSDocument?, Bool, Error?) -> Void)

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

var documents: [NSDocument]

The document objects managed by the receiver.

func addDocument(NSDocument)

Adds the given document to the list of open documents.

var currentDocument: NSDocument?

The document object associated with the main window.

func document(for: NSWindow)

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

var hasEditedDocuments: Bool

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

func removeDocument(NSDocument)

Removes the given document from the list of open documents.

Managing Document Types

var documentClassNames: [String]

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

var defaultType: String?

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

func documentClass(forType: String)

Returns the NSDocument subclass associated with a given document type.

func displayName(forType: String)

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

func typeForContents(of: URL)

Returns, for a specified URL, the document type identifier (such as public.xml or com.example.mydocumenttype) that should be used when opening the document at that location, if successful.


var autosavingDelay: TimeInterval

The time interval (in seconds) for periodic autosaving.

Closing Documents

func closeAllDocuments(withDelegate: Any?, didCloseAllSelector: Selector?, contextInfo: UnsafeMutableRawPointer?)

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

func reviewUnsavedDocuments(withAlertTitle: String?, cancellable: Bool, delegate: Any?, didReviewAllSelector: Selector?, contextInfo: UnsafeMutableRawPointer?)

Displays an alert dialog asking if the user wants to review unsaved documents (only if there are two or more unsaved documents), quit regardless of unsaved documents, or (if the choice is allowed) cancel the impending save operation.

Responding to Action Messages

func newDocument(Any?)

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.

func openDocument(Any?)

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.

func saveAllDocuments(Any?)

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

func beginOpenPanel(completionHandler: ([URL]?) -> Void)

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

func beginOpenPanel(NSOpenPanel, forTypes: [String]?, completionHandler: (Int) -> Void)

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

func runModalOpenPanel(NSOpenPanel, forTypes: [String]?)

Calls the NSOpenPanel runModalForTypes: method, passing the openPanel object and the file extensions associated with a document type.

var currentDirectory: String?

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

func urlsFromRunningOpenPanel()

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

Managing the Open Recent Menu

var maximumRecentDocumentCount: Int

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

func clearRecentDocuments(Any?)

Empties the recent documents list for the application.

func noteNewRecentDocumentURL(URL)

This method should be called by applications not based on NSDocument when they open or save documents identified by the given URL.

func noteNewRecentDocument(NSDocument)

This method is called by NSDocument objects at appropriate times for managing the recent-documents list.

var recentDocumentURLs: [URL]

The list of recent-document URLs.

Validating User Interface Items

func validateUserInterfaceItem(NSValidatedUserInterfaceItem)

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

Handling Errors

func presentError(Error)

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

func willPresentError(Error)

Called when the receiver is about to present an error, returns the error that should actually be presented.

Instance Properties

Instance Methods

See Also


class NSPersistentDocument

A document object that can integrate with Core Data.

class NSDocument

An abstract class that defines the interface for macOS documents.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software