# NSDocument An abstract class that defines the interface for macOS documents. ``` @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`](/documentation/AppKit/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`](/documentation/AppKit/NSDocument) is one of the triad of AppKit classes that establish an architectural basis for document-based apps (the others being [`NSDocumentController`](/documentation/AppKit/NSDocumentController) and [`NSWindowController`](/documentation/AppKit/NSWindowController)). For more information about using [`NSDocument`](/documentation/AppKit/NSDocument) in a document-based app, see [Developing a Document-Based App](/documentation/AppKit/developing-a-document-based-app). ### Subclassing NSDocument The [`NSDocument`](/documentation/AppKit/NSDocument) class is designed to be subclassed. That is, the [`NSDocument`](/documentation/AppKit/NSDocument) class is abstract, and your app must create at least one [`NSDocument`](/documentation/AppKit/NSDocument) subclass in order to use the document architecture. To create a useful [`NSDocument`](/documentation/AppKit/NSDocument) subclass, you must override some methods, and you can optionally override others. The [`NSDocument`](/documentation/AppKit/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. For more information about creating subclasses, including the primitive methods that subclasses must override and those that you can optionally override, see [Developing a Document-Based App](/documentation/AppKit/developing-a-document-based-app). ### Document Saving Behavior The [`NSDocument`](/documentation/AppKit/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:)`](/documentation/AppKit/NSDocument/write(to:ofType:)) and [`write(to:ofType:for:originalContentsURL:)`](/documentation/AppKit/NSDocument/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`](/documentation/AppKit/NSDocument/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:`](/documentation/AppKit/NSDocument/saveToURL:ofType:forSaveOperation:error:) method that is meant always to be invoked during document saving, sets the [`fileModificationDate`](/documentation/AppKit/NSDocument/fileModificationDate) property with the file’s new modification date after it has been written (for [`NSDocument.SaveOperationType.saveOperation`](/documentation/AppKit/NSDocument/SaveOperationType/saveOperation) and [`NSDocument.SaveOperationType.saveAsOperation`](/documentation/AppKit/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:)`](/documentation/AppKit/NSDocument/revert(toContentsOf:ofType:)) method that is meant always to be invoked during rereading of an open document, sets the [`fileModificationDate`](/documentation/AppKit/NSDocument/fileModificationDate) property with the file’s modification date after it has been read. ### iCloud Support The [`NSDocument`](/documentation/AppKit/NSDocument) class implements the file coordination support that is required for an iCloud-enabled, document-based Mac app (see [How iCloud Document Storage Works](https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Chapters/DesigningForDocumentsIniCloud.html#//apple_ref/doc/uid/TP40012094-CH2-SW10) in [iCloud Design Guide](https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Chapters/Introduction.html#//apple_ref/doc/uid/TP40012094)). 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:)`](/documentation/AppKit/NSDocument/canConcurrentlyReadDocuments(ofType:)) class method and return for the appropriate document types. If specific document types rely on shared state information, however, you should return for those types. ## Topics ### Creating a Document Object [`init()`](/documentation/AppKit/NSDocument/init()) Initializes and returns an empty document object. [`convenience init(contentsOf: URL, ofType: String) throws`](/documentation/AppKit/NSDocument/init(contentsOf:ofType:)) Initializes a document located by a URL of a specified type. [`convenience init(for: URL?, withContentsOf: URL, ofType: String) throws`](/documentation/AppKit/NSDocument/init(for:withContentsOf:ofType:)) Initializes a document with the specified contents, and places the resulting document’s file at the designated location. [`convenience init(type: String) throws`](/documentation/AppKit/NSDocument/init(type:)) Initializes a document of a specified type. ### Reading the Document’s Content [`class func canConcurrentlyReadDocuments(ofType: String) -> Bool`](/documentation/AppKit/NSDocument/canConcurrentlyReadDocuments(ofType:)) Returns a Boolean value that indicates whether the receiver reads multiple documents of the given type concurrently. [`func read(from: URL, ofType: String) throws`](/documentation/AppKit/NSDocument/read(from:ofType:)-1vttv) Sets the contents of this document by reading from a file or file package, of a specified type, located by a URL. [`func read(from: FileWrapper, ofType: String) throws`](/documentation/AppKit/NSDocument/read(from:ofType:)-3rzsi) Sets the contents of this document by reading from a file wrapper of a specified type. [`func read(from: Data, ofType: String) throws`](/documentation/AppKit/NSDocument/read(from:ofType:)-6g6ai) Sets the contents of this document by reading from data of a specified type. ### Writing the Document’s Content [`func canAsynchronouslyWrite(to: URL, ofType: String, for: NSDocument.SaveOperationType) -> Bool`](/documentation/AppKit/NSDocument/canAsynchronouslyWrite(to:ofType:for:)) Returns whether the receiver can concurrently write to a file or file package located by a URL, that is formatted for a specific type, for a specific kind of save operation. [`func unblockUserInteraction()`](/documentation/AppKit/NSDocument/unblockUserInteraction()) Unblocks the main thread during asynchronous saving. [`func write(to: URL, ofType: String) throws`](/documentation/AppKit/NSDocument/write(to:ofType:)) Writes the contents of the document to a file or file package located by a URL, that is formatted to a specified type. [`func writeSafely(to: URL, ofType: String, for: NSDocument.SaveOperationType) throws`](/documentation/AppKit/NSDocument/writeSafely(to:ofType:for:)) Writes the contents of the document to a file or file package located by a URL. [`func fileWrapper(ofType: String) throws -> FileWrapper`](/documentation/AppKit/NSDocument/fileWrapper(ofType:)) Creates and returns a file wrapper that contains the contents of the document, formatted to the specified type. [`func data(ofType: String) throws -> Data`](/documentation/AppKit/NSDocument/data(ofType:)) Creates and returns a data object that contains the contents of the document, formatted to a specified type. [`func write(to: URL, ofType: String, for: NSDocument.SaveOperationType, originalContentsURL: URL?) throws`](/documentation/AppKit/NSDocument/write(to:ofType:for:originalContentsURL:)) Writes the contents of the document to a file or file package located by a URL. [`func save(to: URL, ofType: String, for: NSDocument.SaveOperationType, delegate: Any?, didSave: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/save(to:ofType:for:delegate:didSave:contextInfo:)) Saves the contents of the document to a file or file package located by a URL, that is formatted to a specified type, for a particular kind of save operation. [`func save(to: URL, ofType: String, for: NSDocument.SaveOperationType, completionHandler: ((any Error)?) -> Void)`](/documentation/AppKit/NSDocument/save(to:ofType:for:completionHandler:)) Saves the contents of the document to a file or file package located by a URL, that is formatted to a specified type, for a particular kind of save operation, and invokes the passed-in completion handler. [`func fileAttributesToWrite(to: URL, ofType: String, for: NSDocument.SaveOperationType, originalContentsURL: URL?) throws -> [String : Any]`](/documentation/AppKit/NSDocument/fileAttributesToWrite(to:ofType:for:originalContentsURL:)) Returns the attributes to write to the file or file package at the specified URL, and targeting the specified type of save operation. [`enum SaveOperationType`](/documentation/AppKit/NSDocument/SaveOperationType) Constants for specifying the type of document-save operation to perform. ### Getting Document Metadata [`var fileURL: URL?`](/documentation/AppKit/NSDocument/fileURL) The location of the document’s on-disk representation. [`var isEntireFileLoaded: Bool`](/documentation/AppKit/NSDocument/isEntireFileLoaded) A Boolean value that indicates whether the document’s file is completely loaded into memory. [`var fileModificationDate: Date?`](/documentation/AppKit/NSDocument/fileModificationDate) The last-known modification date of the document’s on-disk representation. [`var keepBackupFile: Bool`](/documentation/AppKit/NSDocument/keepBackupFile) A Boolean value that indicates whether the document archives previously saved versions of the document. [`var isDraft: Bool`](/documentation/AppKit/NSDocument/isDraft) A Boolean value that indicates whether the document is a draft that the user has not yet saved. [`var fileType: String?`](/documentation/AppKit/NSDocument/fileType) The name of the document type, as specified in the app’s information property-list file. [`var isDocumentEdited: Bool`](/documentation/AppKit/NSDocument/isDocumentEdited) A Boolean value that indicates whether the document has unsaved changes. [`var isInViewingMode: Bool`](/documentation/AppKit/NSDocument/isInViewingMode) A Boolean value that indicates whether the document is in read-only mode. ### Managing File Type Information [`class var readableTypes: [String]`](/documentation/AppKit/NSDocument/readableTypes) Returns the types of data the receiver can read natively and any types filterable to that native type. [`class var writableTypes: [String]`](/documentation/AppKit/NSDocument/writableTypes) Returns the types of data the receiver can write natively and any types filterable to that native type. [`class func isNativeType(String) -> Bool`](/documentation/AppKit/NSDocument/isNativeType(_:)) Returns a Boolean value that indicates whether the document can read and write the data natively. [`func writableTypes(for: NSDocument.SaveOperationType) -> [String]`](/documentation/AppKit/NSDocument/writableTypes(for:)) Returns the names of the types to which this document can be saved for a specified kind of save operation. [`func fileNameExtension(forType: String, saveOperation: NSDocument.SaveOperationType) -> String?`](/documentation/AppKit/NSDocument/fileNameExtension(forType:saveOperation:)) Returns a filename extension that can be appended to a base filename, for a specified file type and kind of save operation. ### Creating and Managing Window Controllers [`func makeWindowControllers()`](/documentation/AppKit/NSDocument/makeWindowControllers()) Creates the window controller objects that the document uses to display its content. [`func addWindowController(NSWindowController)`](/documentation/AppKit/NSDocument/addWindowController(_:)) Adds the specified window controller to the current document. [`func removeWindowController(NSWindowController)`](/documentation/AppKit/NSDocument/removeWindowController(_:)) Removes the specified window controller from the receiver’s array of window controllers. [`var windowControllers: [NSWindowController]`](/documentation/AppKit/NSDocument/windowControllers) The document’s current window controllers. [`var windowNibName: NSNib.Name?`](/documentation/AppKit/NSDocument/windowNibName) The name of the document’s sole nib file. [`func windowControllerDidLoadNib(NSWindowController)`](/documentation/AppKit/NSDocument/windowControllerDidLoadNib(_:)) Called after one of the document’s window controllers loads its nib file. [`func windowControllerWillLoadNib(NSWindowController)`](/documentation/AppKit/NSDocument/windowControllerWillLoadNib(_:)) Called before one of the document’s window controllers loads its nib file. [`func shouldCloseWindowController(NSWindowController, delegate: Any?, shouldClose: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/shouldCloseWindowController(_:delegate:shouldClose:contextInfo:)) Determines whether the system should close the document and its associated window. ### Managing Document Windows [`func showWindows()`](/documentation/AppKit/NSDocument/showWindows()) Displays all of the document’s windows, bringing them to the front and making them main or key as necessary. [`func setWindow(NSWindow?)`](/documentation/AppKit/NSDocument/setWindow(_:)) Sets the window outlet of this document to the specified value. [`var windowForSheet: NSWindow?`](/documentation/AppKit/NSDocument/windowForSheet) Returns the document window to use as the parent of a document-modal sheet. [`var displayName: String!`](/documentation/AppKit/NSDocument/displayName) The name of the document as displayed in the title bars of the document’s windows and in alert dialogs related to the document. [`func defaultDraftName() -> String`](/documentation/AppKit/NSDocument/defaultDraftName()) Returns the default draft name for the document subclass. [`func encodeRestorableState(with: NSCoder, backgroundQueue: OperationQueue)`](/documentation/AppKit/NSDocument/encodeRestorableState(with:backgroundQueue:)) Saves the interface-related state of the document. ### Configuring the Autosave Behavior [`class var autosavesInPlace: Bool`](/documentation/AppKit/NSDocument/autosavesInPlace) A Boolean value that indicates whether the document subclass supports autosaving in place. [`class var autosavesDrafts: Bool`](/documentation/AppKit/NSDocument/autosavesDrafts) A Boolean value that indicates whether the document subclass supports autosaving of drafts. [`class var preservesVersions: Bool`](/documentation/AppKit/NSDocument/preservesVersions) A Boolean value that indicates whether the document subclass supports version management. [`var autosavedContentsFileURL: URL?`](/documentation/AppKit/NSDocument/autosavedContentsFileURL) The location of the most recently autosaved document contents. [`var autosavingFileType: String?`](/documentation/AppKit/NSDocument/autosavingFileType) The document type to use for an autosave operation. [`var autosavingIsImplicitlyCancellable: Bool`](/documentation/AppKit/NSDocument/autosavingIsImplicitlyCancellable) A Boolean value that indicates whether you can cancel an in-progress autosave operation. ### Autosaving the Document [`func checkAutosavingSafety() throws`](/documentation/AppKit/NSDocument/checkAutosavingSafety()) Returns a Boolean value that indicates whether it is safe to autosave document changes. [`var hasUnautosavedChanges: Bool`](/documentation/AppKit/NSDocument/hasUnautosavedChanges) A Boolean value that indicates whether the document has changes that have not been autosaved. [`func scheduleAutosaving()`](/documentation/AppKit/NSDocument/scheduleAutosaving()) Schedules periodic autosaving for the purpose of crash protection. [`func autosave(withDelegate: Any?, didAutosave: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/autosave(withDelegate:didAutosave:contextInfo:)) Autosaves the document’s contents to an appropriate location in the file system. [`func autosave(withImplicitCancellability: Bool, completionHandler: ((any Error)?) -> Void)`](/documentation/AppKit/NSDocument/autosave(withImplicitCancellability:completionHandler:)) Autosaves the document’s contents to an appropriate file-system location, as needed. [`var backupFileURL: URL?`](/documentation/AppKit/NSDocument/backupFileURL) The URL for the document’s backup file that was created during an autosave operation. ### Browsing Document Versions [`func browseVersions(Any?)`](/documentation/AppKit/NSDocument/browseVersions(_:)) Opens the Versions browser in the document’s main window. [`var isBrowsingVersions: Bool`](/documentation/AppKit/NSDocument/isBrowsingVersions) A Boolean value that indicates whether the document is currently displaying the Versions browser. [`func stopBrowsingVersions(completionHandler: (() -> Void)?)`](/documentation/AppKit/NSDocument/stopBrowsingVersions(completionHandler:)) Dismiss the Versions browser for the current document. ### Storing Documents in iCloud [`func moveToUbiquityContainer(Any?)`](/documentation/AppKit/NSDocument/moveToUbiquityContainer(_:)) Moves the document to the user’s iCloud storage. [`class var usesUbiquitousStorage: Bool`](/documentation/AppKit/NSDocument/usesUbiquitousStorage) Returns whether the document object stores its contents in the user’s iCloud document storage. ### Managing Undo and Redo Actions [`var undoManager: UndoManager?`](/documentation/AppKit/NSDocument/undoManager) The object that the document uses to support undo/redo operations. [`var hasUndoManager: Bool`](/documentation/AppKit/NSDocument/hasUndoManager) A Boolean value that indicates whether the document owns an undo manager object. ### Updating the Document Change Count [`func updateChangeCount(withToken: Any, for: NSDocument.SaveOperationType)`](/documentation/AppKit/NSDocument/updateChangeCount(withToken:for:)) Updates the document’s change count settings after a successful save operation. [`func updateChangeCount(NSDocument.ChangeType)`](/documentation/AppKit/NSDocument/updateChangeCount(_:)) Updates the receiver’s change count according to the given change type. [`enum ChangeType`](/documentation/AppKit/NSDocument/ChangeType) Values that indicate a document’s edit status. [`func changeCountToken(for: NSDocument.SaveOperationType) -> Any`](/documentation/AppKit/NSDocument/changeCountToken(for:)) Returns an object that encapsulates the current record of document changes at the beginning of a save operation. ### Handling Window Restoration [`class func allowedClasses(forRestorableStateKeyPath: String) -> [AnyClass]`](/documentation/AppKit/NSDocument/allowedClasses(forRestorableStateKeyPath:)) Returns the classes that support secure coding. [`func encodeRestorableState(with: NSCoder)`](/documentation/AppKit/NSDocument/encodeRestorableState(with:)) Saves the interface-related state of the document. [`func restoreState(with: NSCoder)`](/documentation/AppKit/NSDocument/restoreState(with:)) Restores the interface-related state of the document. [`class var restorableStateKeyPaths: [String]`](/documentation/AppKit/NSDocument/restorableStateKeyPaths) Returns an array of key paths that represent the restorable attributes of the document. [`func invalidateRestorableState()`](/documentation/AppKit/NSDocument/invalidateRestorableState()) Marks the document’s interface-related state as dirty. [`func restoreWindow(withIdentifier: NSUserInterfaceItemIdentifier, state: NSCoder, completionHandler: (NSWindow?, (any Error)?) -> Void)`](/documentation/AppKit/NSDocument/restoreWindow(withIdentifier:state:completionHandler:)) Restores a window that was associated with a document, after that document is reopened. ### Presenting a Save Panel [`func runModalSavePanel(for: NSDocument.SaveOperationType, delegate: Any?, didSave: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/runModalSavePanel(for:delegate:didSave:contextInfo:)) Presents a modal Save panel to the user, then tries to save the document if the user approves the operation. [`func prepareSavePanel(NSSavePanel) -> Bool`](/documentation/AppKit/NSDocument/prepareSavePanel(_:)) Tells the document to customize the specified Save panel. [`var shouldRunSavePanelWithAccessoryView: Bool`](/documentation/AppKit/NSDocument/shouldRunSavePanelWithAccessoryView) A Boolean value that indicates whether the document’s Save panel displays a list of supported writable document types. [`var fileTypeFromLastRunSavePanel: String?`](/documentation/AppKit/NSDocument/fileTypeFromLastRunSavePanel) The file type that was last selected in the Save panel. [`var fileNameExtensionWasHiddenInLastRunSavePanel: Bool`](/documentation/AppKit/NSDocument/fileNameExtensionWasHiddenInLastRunSavePanel) A Boolean value that indicates whether the user chose to hide the document’s filename extension. ### Supporting User Activities [`var userActivity: NSUserActivity?`](/documentation/AppKit/NSDocument/userActivity) An object that encapsulates a user activity the document supports. [`func updateUserActivityState(NSUserActivity)`](/documentation/AppKit/NSDocument/updateUserActivityState(_:)) Updates the state of the given user activity. [`let NSUserActivityDocumentURLKey: String`](/documentation/AppKit/NSUserActivityDocumentURLKey) The key that identifies the document associated with a user activity. ### Validating User Interface Items [`func validateUserInterfaceItem(any NSValidatedUserInterfaceItem) -> Bool`](/documentation/AppKit/NSDocument/validateUserInterfaceItem(_:)) Validates the specified user interface item that the receiver manages. ### Performing Tasks Serially [`func performSynchronousFileAccess(() -> Void)`](/documentation/AppKit/NSDocument/performSynchronousFileAccess(_:)) Waits for any scheduled file access to complete, then invokes the passed-in block. [`func performAsynchronousFileAccess((() -> Void) -> Void)`](/documentation/AppKit/NSDocument/performAsynchronousFileAccess(_:)) Waits for any scheduled file access to complete but without blocking the main thread, then invokes the passed-in block. [`func performActivity(withSynchronousWaiting: Bool, using: (() -> Void) -> Void)`](/documentation/AppKit/NSDocument/performActivity(withSynchronousWaiting:using:)) Waits for any work scheduled by previous invocations of this method to complete, then invokes the passed-in block. [`func continueActivity(() -> Void)`](/documentation/AppKit/NSDocument/continueActivity(_:)) Continues to perform the task for a user activity object using a different block. [`func continueAsynchronousWorkOnMainThread(() -> Void)`](/documentation/AppKit/NSDocument/continueAsynchronousWorkOnMainThread(_:)) Invokes the passed-in block on the main thread. ### Handling User Actions [`func printDocument(Any?)`](/documentation/AppKit/NSDocument/printDocument(_:)) Prints the receiver in response to the user choosing the Print menu command. [`func runPageLayout(Any?)`](/documentation/AppKit/NSDocument/runPageLayout(_:)) The action method invoked in the receiver as first responder when the user chooses the Page Setup menu command. [`func revertToSaved(Any?)`](/documentation/AppKit/NSDocument/revertToSaved(_:)) The action of the File menu item Revert in a document-based app. [`func save(Any?)`](/documentation/AppKit/NSDocument/save(_:)) The action method invoked in the receiver as first responder when the user chooses the Save menu command. [`func saveAs(Any?)`](/documentation/AppKit/NSDocument/saveAs(_:)) The action method invoked in the receiver as first responder when the user chooses the Save As menu command. [`func saveTo(Any?)`](/documentation/AppKit/NSDocument/saveTo(_:)) The action method invoked in the receiver as first responder when the user chooses the Save To menu command. [`func save(withDelegate: Any?, didSave: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/save(withDelegate:didSave:contextInfo:)) Saves the document and delivers the results to the provided delegate object. ### Closing the Document [`func canClose(withDelegate: Any, shouldClose: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/canClose(withDelegate:shouldClose:contextInfo:)) Determines whether to close the document, prompting the user as needed to choose a course of action. [`func close()`](/documentation/AppKit/NSDocument/close()) Closes all of the document’s windows and removes the document from its document controller. ### Reverting the Document Contents [`func revert(toContentsOf: URL, ofType: String) throws`](/documentation/AppKit/NSDocument/revert(toContentsOf:ofType:)) Discards all unsaved document modifications and replaces the document’s contents by reading a file or file package located by a URL of a specified type. ### Duplicating the Document [`func duplicate() throws -> NSDocument`](/documentation/AppKit/NSDocument/duplicate()) Creates a new document whose contents are the same as the receiver and returns an error object if unsuccessful. [`func duplicate(Any?)`](/documentation/AppKit/NSDocument/duplicate(_:)) Creates a copy of the receiving document in response to the user choosing Duplicate from the File menu. [`func duplicate(withDelegate: Any?, didDuplicate: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/duplicate(withDelegate:didDuplicate:contextInfo:)) Creates a new document whose contents are the same as the current document. ### Renaming the Document [`func rename(Any?)`](/documentation/AppKit/NSDocument/rename(_:)) Renames the current document in response to the user choosing the Rename menu item. ### Moving the Document [`func move(Any?)`](/documentation/AppKit/NSDocument/move(_:)) Moves the document to a new location in response to the user choosing the Move To… menu item. [`func move(completionHandler: ((Bool) -> Void)?)`](/documentation/AppKit/NSDocument/move(completionHandler:)) Moves the document to a user-selected location. [`func move(to: URL, completionHandler: (((any Error)?) -> Void)?)`](/documentation/AppKit/NSDocument/move(to:completionHandler:)) Moves the document’s file to the given URL. ### Locking the Document [`func lock(Any?)`](/documentation/AppKit/NSDocument/lock(_:)) Locks the document in response to the user choosing the Lock menu item. [`func unlock(Any?)`](/documentation/AppKit/NSDocument/unlock(_:)) Unlocks the document in response to the user choosing the Unlock menu item. [`func lock(completionHandler: ((Bool) -> Void)?)`](/documentation/AppKit/NSDocument/lock(completionHandler:)-6zuhh) Prevents the user from making further changes to the document. [`func lock(completionHandler: (((any Error)?) -> Void)?)`](/documentation/AppKit/NSDocument/lock(completionHandler:)-161qv) Prevents the user from making changes to the document’s file. [`func unlock(completionHandler: ((Bool) -> Void)?)`](/documentation/AppKit/NSDocument/unlock(completionHandler:)-8p8zd) Allows the user to make modifications to the document. [`func unlock(completionHandler: (((any Error)?) -> Void)?)`](/documentation/AppKit/NSDocument/unlock(completionHandler:)-6m7rh) Allows the user to make modifications to the document’s file. [`var isLocked: Bool`](/documentation/AppKit/NSDocument/isLocked) A Boolean value that indicates whether or not the file can be written to. ### Printing the Document [`var printInfo: NSPrintInfo`](/documentation/AppKit/NSDocument/printInfo) The printing information associated with the document. [`func preparePageLayout(NSPageLayout) -> Bool`](/documentation/AppKit/NSDocument/preparePageLayout(_:)) Adds document-specific content to the Page Layout panel. [`func runModalPageLayout(with: NSPrintInfo, delegate: Any?, didRun: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/runModalPageLayout(with:delegate:didRun:contextInfo:)) Runs the modal page layout panel with the receiver’s printing information object. [`func runModalPrintOperation(NSPrintOperation, delegate: Any?, didRun: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/runModalPrintOperation(_:delegate:didRun:contextInfo:)) Runs the specified print operation modally. [`func shouldChangePrintInfo(NSPrintInfo) -> Bool`](/documentation/AppKit/NSDocument/shouldChangePrintInfo(_:)) Returns a Boolean value that indicates whether the document allows changes to the default printing information. [`func print(withSettings: [NSPrintInfo.AttributeKey : Any], showPrintPanel: Bool, delegate: Any?, didPrint: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/print(withSettings:showPrintPanel:delegate:didPrint:contextInfo:)) Prints the document’s contents, optionally displaying a print panel to the user. [`func printOperation(withSettings: [NSPrintInfo.AttributeKey : Any]) throws -> NSPrintOperation`](/documentation/AppKit/NSDocument/printOperation(withSettings:)) Creates and returns a print operation for the document’s contents. [`var pdfPrintOperation: NSPrintOperation`](/documentation/AppKit/NSDocument/pdfPrintOperation) A print operation you can use to create a PDF representation of the document’s current contents. [`func saveToPDF(Any?)`](/documentation/AppKit/NSDocument/saveToPDF(_:)) Exports a PDF representation of the document’s current contents. ### Sharing the Document [`var allowsDocumentSharing: Bool`](/documentation/AppKit/NSDocument/allowsDocumentSharing) A Boolean value that indicates whether the document is shareable from the standard Share menu. [`func prepare(NSSharingServicePicker)`](/documentation/AppKit/NSDocument/prepare(_:)) Perform any custom setup associated with a sharing service picker. [`func share(with: NSSharingService, completionHandler: ((Bool) -> Void)?)`](/documentation/AppKit/NSDocument/share(with:completionHandler:)) Share the document’s file using the specified sharing service. ### Handling Script Commands [`func handleClose(NSCloseCommand) -> Any?`](/documentation/AppKit/NSDocument/handleClose(_:)) Handles the Close AppleScript command by attempting to close the document. [`func handlePrint(NSScriptCommand) -> Any?`](/documentation/AppKit/NSDocument/handlePrint(_:)) Handles the Print AppleScript command by attempting to print the document. [`func handleSave(NSScriptCommand) -> Any?`](/documentation/AppKit/NSDocument/handleSave(_:)) Handles the Save AppleScript command by attempting to save the document. [`var objectSpecifier: NSScriptObjectSpecifier`](/documentation/AppKit/NSDocument/objectSpecifier) Returns the object specifier that represents the document. [`var lastComponentOfFileName: String`](/documentation/AppKit/NSDocument/lastComponentOfFileName) The name of the document seen by the user in AppleScript. ### Displaying Errors to the User [`func presentError(any Error, modalFor: NSWindow, delegate: Any?, didPresent: Selector?, contextInfo: UnsafeMutableRawPointer?)`](/documentation/AppKit/NSDocument/presentError(_:modalFor:delegate:didPresent:contextInfo:)) Presents an error alert to the user as a modal panel. [`func presentError(any Error) -> Bool`](/documentation/AppKit/NSDocument/presentError(_:)) Presents an error alert to the user as a modal panel. [`func willPresentError(any Error) -> any Error`](/documentation/AppKit/NSDocument/willPresentError(_:)) Called when the receiver is about to present an error. [`func willNotPresentError(any Error)`](/documentation/AppKit/NSDocument/willNotPresentError(_:)) Confirms that the error object is not to be presented to the user and the error cannot be recovered from, so cleanup can be done. ### Deprecated Avoid using deprecated classes and protocols in your apps. [Deprecated Symbols](/documentation/AppKit/nsdocument-deprecated-symbols) Review symbols that are no longer supported, and find replacements. ### Instance Properties [`var observedPresentedItemUbiquityAttributes: Set`](/documentation/AppKit/NSDocument/observedPresentedItemUbiquityAttributes) [`var presentedItemURL: URL?`](/documentation/AppKit/NSDocument/presentedItemURL) [`var previewRepresentableActivityItems: [any NSPreviewRepresentableActivityItem]?`](/documentation/AppKit/NSDocument/previewRepresentableActivityItems) ### Instance Methods [`func accommodatePresentedItemDeletion(completionHandler: ((any Error)?) -> Void)`](/documentation/AppKit/NSDocument/accommodatePresentedItemDeletion(completionHandler:)) [`func presentedItemDidChange()`](/documentation/AppKit/NSDocument/presentedItemDidChange()) [`func presentedItemDidChangeUbiquityAttributes(Set)`](/documentation/AppKit/NSDocument/presentedItemDidChangeUbiquityAttributes(_:)) [`func presentedItemDidGain(NSFileVersion)`](/documentation/AppKit/NSDocument/presentedItemDidGain(_:)) [`func presentedItemDidLose(NSFileVersion)`](/documentation/AppKit/NSDocument/presentedItemDidLose(_:)) [`func presentedItemDidMove(to: URL)`](/documentation/AppKit/NSDocument/presentedItemDidMove(to:)) [`func presentedItemDidResolveConflict(NSFileVersion)`](/documentation/AppKit/NSDocument/presentedItemDidResolveConflict(_:)) [`func relinquishPresentedItem(toReader: ((() -> Void)?) -> Void)`](/documentation/AppKit/NSDocument/relinquishPresentedItem(toReader:)) [`func relinquishPresentedItem(toWriter: ((() -> Void)?) -> Void)`](/documentation/AppKit/NSDocument/relinquishPresentedItem(toWriter:)) [`func savePresentedItemChanges(completionHandler: ((any Error)?) -> Void)`](/documentation/AppKit/NSDocument/savePresentedItemChanges(completionHandler:)) ### Initializers [`convenience init(contentsOfURL: URL, ofType: String) throws`](/documentation/AppKit/NSDocument/init(contentsOfURL:ofType:)) [`convenience init(forURL: URL?, withContentsOfURL: URL, ofType: String) throws`](/documentation/AppKit/NSDocument/init(forURL:withContentsOfURL:ofType:)) ### Instance Properties [`var savePanelShowsFileFormatsControl: Bool`](/documentation/AppKit/NSDocument/savePanelShowsFileFormatsControl) ## Relationships ### Conforms To [`CVarArg`](/documentation/Swift/CVarArg) [`Sendable`](/documentation/Swift/Sendable) [`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible) [`Escapable`](/documentation/Swift/Escapable) [`NSUserActivityRestoring`](/documentation/AppKit/NSUserActivityRestoring) [`NSMenuItemValidation`](/documentation/AppKit/NSMenuItemValidation) [`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible) [`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol) [`NSFilePresenter`](/documentation/Foundation/NSFilePresenter) [`Hashable`](/documentation/Swift/Hashable) [`NSEditorRegistration`](/documentation/AppKit/NSEditorRegistration) [`Copyable`](/documentation/Swift/Copyable) [`Equatable`](/documentation/Swift/Equatable) [`NSUserInterfaceValidations`](/documentation/AppKit/NSUserInterfaceValidations) ### Inherited By [`NSPersistentDocument`](/documentation/AppKit/NSPersistentDocument) ### Inherits From [`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class) --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)