---

Autosaving in the Document Architecture

In Mac OS X v10.4 and later, the  document-based application architecture supports autosaving documents. The support takes the form of application behavior and NSDocument and NSDocumentController methods that you can call or override to customize the behavior.

Contents:

Autosaving Behavior
NSDocumentController Autosaving Methods
NSDocument Methods

Autosaving Behavior

Autosaving is the mechanism by which the document architecture automatically saves a document to disk, at some regular interval, while it is being edited by the user. Autosaving protects the user from data loss in case of power failure, application crashes, and so on. By default, autosaving is not turned on in the document architecture, but you can easily turn it on by sending a single message to your application's NSDocumentController object.

To turn on autosaving in a document-based application, you need only send a setAutosavingDelay: message to the NSDocumentController object with a parameter value greater than 0. You can customize autosaving behavior by overriding autosaving-related methods in NSDocument and NSDocumentController.

During normal operation of an application with autosaving turned on, the document architecture autosaves untitled documents, by default, in the folder ~/Library/Autosave Information/ until the user saves the document. Thereafter, by default, autosaved documents go in the same folder where the user saved the document. When a document is saved by the user or the application quits normally, autosaved documents are deleted.

When an application with autosaving turned on crashes or otherwise quits abnormally, its autosaved documents retain on disk all of the content changes made to the time of the last autosave. When the application is relaunched, it automatically reopens its autosaved documents.

NSDocumentController Autosaving Methods

NSDocumentController has four methods related to autosaving. One method turns autosaving on and sets its interval. By invoking or overriding the other methods, you can customize autosaving behavior. Two methods relate to when documents are autosaved. Two other methods enable you to customize what is done when autosaved documents are reopened at application launch time.

The method that controls when (and whether) documents are autosaved is setAutosavingDelay:, which sets the time interval, in seconds, for periodic autosaving. This time interval is the time the document controller waits between detecting that a document has unsaved changes and sending the document an autosaveDocumentWithDelegate:didAutosaveSelector:contextInfo: message. A value of 0 indicates that autosaving is not done at all. By default, the value is 0, so autosaving is off. The autosavingDelay method returns the current autosaving time interval.

The NSDocumentController methods you can use to customize reopening of autosave documents are reopenDocumentForURL:withContentsOfURL:error:, which the document controller invokes to reopen its autosaved documents, and makeDocumentForURL:withContentsOfURL:ofType:error:, which determines the class of document to instantiate, allocates a document object, and sends it an initForURL:withContentsOfURL:ofType:error: message.

NSDocument Methods

NSDocument also has methods related to autosaving. You don't need to use them to enable or configure autosaving in your application, but you can invoke or override them if you want to customize autosaving behavior.

The initForURL:withContentsOfURL:ofType:error: method does the actual initialization of the document object during reopening of an autosaved document. This method initializes the document located by a specified URL but reads the contents from another URL, where the autosaved file is located.

You can use the setAutosavedContentsFileURL: method to set the location to which documents are autosaved, and autosavedContentsFileURL returns that location.

The autosaveDocumentWithDelegate:didAutosaveSelector:contextInfo: method autosaves the document. The default implementation of this method figures out where the document should be autosaved and calls the NSDocument method saveToURL:ofType:forSaveOperation:delegate:didSaveSelector:contextInfo: to perform the save operation. If you override that method or any NSDocument method that writes to disk and contains a URL parameter, take care to write the file just where the URL parameter specifies. You should not assume that there is a relationship between the document and the value returned by fileURL.

You can test the current state of autosaving for a document by sending it the hasUnautosavedChanges message, which returns YES if the document has changes that have not been autosaved.

The autosavingFileType method returns the document type that should be used for an autosave operation. You can override this method to return nil to completely disable autosaving of an individual document. You can also override this method to return a special document type if, for example, your application defines a document type specifically designed for autosaving, such as one that efficiently represents document changes instead of complete document contents.

---