Contents

NSDocument

An abstract class that defines the interface for macOS documents.

Declaration

@MainActor class NSDocument

Overview

A document is an object that can internally represent data displayed in a window and that can read data from and write data to a file or file package. Documents create and manage one or more window controllers and are in turn managed by a document controller. Documents respond to first-responder action messages to save, revert, and print their data.

Conceptually, a document is a container for a body of information identified by a name under which it is stored in a disk file. In this sense, however, the document is not the same as the file but is an object in memory that owns and manages the document data. In the context of AppKit, a document is an instance of a custom NSDocument subclass that knows how to represent internally, in one or more formats, persistent data that is displayed in windows.

A document can read that data from a file and write it to a file. It is also the first-responder target for many menu commands related to documents, such as Save, Revert, and Print. A document manages its window’s edited status and is set up to perform undo and redo operations. When a window is closing, the document is asked before the window delegate to approve the closing.

NSDocument is one of the triad of AppKit classes that establish an architectural basis for document-based apps (the others being NSDocumentController and NSWindowController).

For more information about using NSDocument in a document-based app, see Developing a Document-Based App.

Subclassing NSDocument

The NSDocument class is designed to be subclassed. That is, the NSDocument class is abstract, and your app must create at least one NSDocument subclass in order to use the document architecture. To create a useful NSDocument subclass, you must override some methods, and you can optionally override others.

The NSDocument class itself knows how to handle document data as undifferentiated lumps; although it understands that these lumps are typed, it knows nothing about particular types. In their overrides of the data-based reading and writing methods, subclasses must add the knowledge of particular types and how data of the document’s native type is structured internally. Subclasses are also responsible for the creation of the window controllers that manage document windows and for the implementation of undo and redo. The NSDocument class takes care of much of the rest, including generally managing the state of the document.

See Document-Based App Programming Guide for Mac for more information about creating subclasses of NSDocument, particularly the list of primitive methods that subclasses must override and those that you can optionally override.

Document Saving Behavior

The NSDocument class implements document saving in a way that preserves, when possible, various attributes of each document, including:

  • Creation date

  • Permissions/privileges

  • Location of the document’s icon in its parent folder’s Icon View Finder window

  • Value of the document’s Show Extension setting

Care is also taken to save documents in a way that does not break any user-created aliases that may point to documents. As a result, some methods in any class of NSDocument may be invoked with parameters that do not have the same meaning as they did in early releases of macOS. It is important that overrides of write(to:ofType:) and write(to:ofType:for:originalContentsURL:) make no assumptions about the file paths passed as parameters, including:

  • The location to which the file is being written. This location might be a hidden temporary directory.

  • The name of the file being written. It is possible that this file has no obvious relation to the document name.

  • The relation of any file being passed, including the original file, to the value in fileURL.

When updating your app to link against OS X v10.5, keep in mind that it is usually more appropriate to invoke in your app code one of the NSDocument save... methods than one of the write... methods. The write... methods are there primarily for you to override. The saveToURL:ofType:forSaveOperation:error: method that is meant always to be invoked during document saving, sets the fileModificationDate property with the file’s new modification date after it has been written (for NSDocument.SaveOperationType.saveOperation and NSDocument.SaveOperationType.saveAsOperation only).

Likewise, it’s usually more appropriate to invoke in your app code one of the NSDocument revert... methods than one of the read... methods. The read... methods are there primarily for you to override. The revert(toContentsOf:ofType:) method that is meant always to be invoked during rereading of an open document, sets the fileModificationDate property with the file’s modification date after it has been read.

iCloud Support

The NSDocument class implements the file coordination support that is required for an iCloud-enabled, document-based Mac app (see How iCloud Document Storage Works in iCloud Design Guide). In addition, this class’s methods for moving and renaming documents, new in OS X v10.8, ensure that these operations are performed in a safe manner for iCloud-enabled apps.

Multicore Considerations

In macOS 10.6 and later, NSDocument supports the ability to open multiple documents concurrently. However, this support requires the cooperation of the document object. If your document subclass is able to read specific document types independently of other similar documents, you should override the canConcurrentlyReadDocuments(ofType:) class method and return true for the appropriate document types. If specific document types rely on shared state information, however, you should return false for those types.

Topics

Creating a Document Object

Reading the Document’s Content

Writing the Document’s Content

Getting Document Metadata

Managing File Type Information

Creating and Managing Window Controllers

Managing Document Windows

Configuring the Autosave Behavior

Autosaving the Document

Browsing Document Versions

Storing Documents in iCloud

Managing Undo and Redo Actions

Updating the Document Change Count

Handling Window Restoration

Presenting a Save Panel

Supporting User Activities

Validating User Interface Items

Performing Tasks Serially

Handling User Actions

Closing the Document

Reverting the Document Contents

Duplicating the Document

Renaming the Document

Moving the Document

Locking the Document

Printing the Document

Sharing the Document

Handling Script Commands

Displaying Errors to the User

Deprecated

Instance Properties

Instance Methods

Initializers

See Also

Documents