An NSDocument​Controller 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 NSDocument​Controller runs and manages the modal Open panel. NSDocument​Controller objects also maintain and manage the mappings of document types, extensions, and NSDocument subclasses as specified in the CFBundle​Document​Types property loaded from the information property list (Info.plist).


You can use various NSDocument​Controller 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 NSDocument​Controller in non-NSDocument-based applications to get some of its features. For example, the NSDocument​Controller management of the Open Recent menu is useful in applications that don’t use subclasses of NSDocument.


Obtaining the Shared Document Controller

class func shared()

Returns the shared NSDocument​Controller instance.

Initializing a New NSDocumentController


This method is the designated initializer for NSDocument​Controller.

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 duplicate​Document(with​Contents​Of:​ URL, copying:​ Bool, display​Name:​ 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 open​Document(with​Contents​Of:​ URL, display:​ Bool, completion​Handler:​ (NSDocument?, Bool, Error?) -> Void)

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

func open​Untitled​Document​And​Display(Bool)

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

func make​Document(for:​ URL?, with​Contents​Of:​ URL, of​Type:​ 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 make​Document(with​Contents​Of:​ URL, of​Type:​ String)

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

func make​Untitled​Document(of​Type:​ String)

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

func reopen​Document(for:​ URL?, with​Contents​Of:​ URL, display:​ Bool, completion​Handler:​ (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 add​Document(NSDocument)

Adds the given document to the list of open documents.

var current​Document:​ 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 has​Edited​Documents:​ Bool

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

func remove​Document(NSDocument)

Removes the given document from the list of open documents.

Managing Document Types

var document​Class​Names:​ [String]

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

var default​Type:​ String?

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

func document​Class(for​Type:​ String)

Returns the NSDocument subclass associated with a given document type.

func display​Name(for​Type:​ 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 type​For​Contents(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 autosaving​Delay:​ Time​Interval

The time interval (in seconds) for periodic autosaving.

Closing Documents

func close​All​Documents(with​Delegate:​ Any?, did​Close​All​Selector:​ Selector?, context​Info:​ Unsafe​Mutable​Raw​Pointer?)

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

func review​Unsaved​Documents(with​Alert​Title:​ String?, cancellable:​ Bool, delegate:​ Any?, did​Review​All​Selector:​ Selector?, context​Info:​ Unsafe​Mutable​Raw​Pointer?)

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 new​Document(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 open​Document(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 save​All​Documents(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 begin​Open​Panel(completion​Handler:​ ([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 begin​Open​Panel(NSOpen​Panel, for​Types:​ [String]?, completion​Handler:​ (Int) -> Void)

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

func run​Modal​Open​Panel(NSOpen​Panel, for​Types:​ [String]?)

Calls the NSOpen​Panel run​Modal​For​Types:​ method, passing the open​Panel object and the file extensions associated with a document type.

var current​Directory:​ String?

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

func urls​From​Running​Open​Panel()

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

Managing the Open Recent Menu

var maximum​Recent​Document​Count:​ Int

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

func clear​Recent​Documents(Any?)

Empties the recent documents list for the application.

func note​New​Recent​Document​URL(URL)

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

func note​New​Recent​Document(NSDocument)

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

var recent​Document​URLs:​ [URL]

The list of recent-document URLs.

Validating User Interface Items

func validate​User​Interface​Item(NSValidated​User​Interface​Item)

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

Handling Errors

func present​Error(Error)

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

func will​Present​Error(Error)

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