Class: UIDocument

Overridden to return a change token for a specific save operation. To get autosaving capabilities for your documents, you must implement change tracking. Typically you do this by using an NSUndoManager object (assigned to undoManager property) to register changes or by calling the updateChangeCount: method every time the user makes a change; UIKit then automatically determines whether there are unsaved changes and returns the proper value from hasUnsavedChanges. If you take neither of these approaches (and you want the autosaving feature), you must implement this method as well as updateChangeCountWithToken:forSaveOperation: and hasUnsavedChanges.You implement this particular method to return a change-count token that UIKit uses to encapsulate the history of document changes for a particular save operation. The token can be any object that represents the current change state of the document. This method is called at the start of the default implementation of the saveToURL:forSaveOperation:completionHandler: method. At the end of this default implementation, it calls the updateChangeCountWithToken:forSaveOperation: method, passing in the change-count token. You implement the latter method to compare the token with the one returned earlier; by doing so, you can determine if the document has acquired new unsaved changes between the start and end of an asynchronous write operation. You can then return the proper value from your override of hasUnsavedChanges.

Asynchronously closes the document after saving any changes. You call this method to begin the sequence of method calls that saves a document safely and asynchronously. The file-system location of the document derives from the fileURL property. After the save operation concludes, the code in completionHandler is executed. In this code, you can close the document—for example, by removing the document’s view from the screen. Additionally, if the save operation did not succeed (success is NO), you can respond in an appropriate manner.You typically would not override this method. The default implementation calls the autosaveWithCompletionHandler: method.

Overridden to return the document data to be saved. Most subclasses of UIDocument override this method to provide UIKit with the document data for saving. If you want more control over the saving operation—for example, you want to perform incremental writing of data—override instead one of the lower-level data-writing methods such as writeContents:andAttributes:safelyToURL:forSaveOperation:error: or writeContents:toURL:forSaveOperation:originalContentsURL:error:. Note that these methods are called on a background thread.This method is called on the queue on which saveToURL:forSaveOperation:completionHandler: was invoked (typically the main queue). The actual writing of data occurs on a background queue. The default implementation returns nil.

Overridden to disable editing when it is unsafe to make changes to a document. Subclasses should override this method to prevent the user from editing the document when it is unsafe to do so, such as during a save-and-close or revert operation. When editing is safe again, UIKit class calls enableEditing. The default implementation of this method does nothing.

Overridden to enable editing when it is safe again to make changes to a document. Subclasses should override this method to allow the user to edit the document when it is safe to do so. This method override should be paired with an override of disableEditing. The default implementation of this method does nothing.

Returns a dictionary of file attributes to associate with the document file when writing or updating it. The attributes are associated with a specific file type and save operation. You can override this method to return a dictionary of file attributes that are different than the default file attribute, which for new files is NSFileExtensionHidden. The saveToURL:forSaveOperation:completionHandler: calls this method before executing asynchronous writing. It passes the dictionary into writeContents:andAttributes:safelyToURL:forSaveOperation:error: when it calls that method to write the document file.

Returns a file extension to append to the file URL of the document file being written. The default implementation queries Launch Services to obtain the file extension matching the file (document) type. You can override this method to return a file extension that is different from the default extension. The default implementation of the saveToURL:forSaveOperation:completionHandler: method calls this method before it gets the document content and writes the document file to disk.

Tells UIKit that you have finished handled the error. This method is called by default when handling of an error (including any user interaction) is complete. Subclasses need to call this method only if they override handleError:userInteractionPermitted: and do not call the superclass implementation (super). If you override this method, you must call super.

Called or overridden to handle an error that occurs during an attempt to read, save, or revert a document. Typical subclasses do not need to call or override this method. Instead, they can observe the UIDocumentStateChangedNotification notification to be notified of changes in document state. In their notification handler, they can check the value of the documentState property and proceed accordingly. See “Conflict Resolution and Error Handling” for a discussion of this. If you directly call any of the advanced reading and writing methods that have an error-object parameter (for example, writeContents:andAttributes:safelyToURL:forSaveOperation:error:) and that call returns an NSError object by indirection, you should call this method (handleError:userInteractionPermitted:), passing in the error object.This method is called by the default implementations of openWithCompletionHandler: and saveToURL:forSaveOperation:completionHandler: when UIDocument encounters a reading or writing error, respectively. If you override this method and do not invoke the superclass implementation (super), you are responsible for the following: Calling finishedHandlingError:recovered: when you are finished handling the error—for example, when the application does not require any additional user feedback about the error.Implementing userInteractionNoLongerPermittedForError: to conclude error handling immediately. If userInteractionPermitted is NO, you should immediately handle the error and call finishedHandlingError:recovered: within the context of the handleError:userInteractionPermitted:

Returns whether the document has any unsaved changes. The default implementation of autosaveWithCompletionHandler: initiates a save if this method returns YES. Typical subclasses do not need to override the hasUnsavedChanges method. To implement change tracking, they should instead use an NSUndoManager object (assigned to undoManager) to register changes or call updateChangeCount: every time the user makes a change; UIKit then automatically determines whether there are unsaved changes.

Returns a document object initialized with its file-system location. After you create a document object and no file exists for it yet, you should next call the saveToURL:forSaveOperation:completionHandler: to write the document to its file-system location in the application sandbox. If url locates an existing document file, call openWithCompletionHandler: after creating the document object. The second parameter of this method, the save operation constant, should be UIDocumentSaveForCreating when there is no document file yet. In the completion handler, if you want the document to be automatically synced with other devices and computers on which the application is installed, you should call the NSFileManager method setMobileSynchEnabled:forItemAtURL:destinationDirectory:replacementURL:error:.

Overridden to load the document data into the application’s data model. Most subclasses of UIDocument override this method to accept and load the data for a document. After UIDocument reads the document data from the file located at fileURL it calls the subclass, passing the data to the subclass in this method. This method is called by the readFromURL:error: method.

Opens a document asynchronously. You call this method to begin the sequence of method calls that opens and reads a document asynchronously. The method obtains the file-system location of the document from the fileURL property. After the open operation concludes, the code in completionHandler is executed.You can override this method if you want custom document-opening behavior, but if you do it is recommended that you call the superclass implementation first (super). If you don’t call super, you should use the NSFileCoordinator class to implement coordinated reading. The default implementation sets up file coordination and then calls performAsynchronousFileAccessUsingBlock: to schedule the document-reading work for execution on a background queue. The queued task then calls readFromURL:error:.

Schedules a document-reading or document-writing operation on a concurrent background queue. A typical UIDocument subclasses—that is, one that overrides contentsForType:error: and loadFromContents:ofType:error:— does not need to call this method. The default implementations of saveToURL:forSaveOperation:completionHandler: and openWithCompletionHandler: call this method to serialize file access. If you override these methods and do not call super, you should call this method to serialize file access on a background queue. If you directly call the readFromURL:error: method, you should wrap that call in the block passed into performAsynchronousFileAccessUsingBlock:.

Reads the document data in a file at a specified location in the application sandbox. Typical UIDocument subclasses should not need to call this method directly, especially if the entire file is read at once. The default implementation calls loadFromContents:ofType:error: on the queue on which openWithCompletionHandler: was called to provide the UIDocument subclass with the document data object.Subclasses that want more control over the reading of the document file—for example, that want to read a large document file incrementally—can override this method. It is not necessary for these subclasses to call the superclass implementation (super).

Reverts a document to the most recent document data stored on-disk. You call this method to discard all unsaved document modifications and replace the document's contents by reading the file or file package located by url. The default implementation brackets the reversion operation between disableEditing and enableEditingbecause the document should not accept user changes during this period. Subclasses that override this method must call the superclass implementation (super) or use the NSFileCoordinator class to initiate a coordinated read.

Saves document data to the specified location in the application sandbox. The default implementation of this method first calls the contentsForType:error: method synchronously on the calling queue to get the document data to save. Then it calls the writeContents:andAttributes:safelyToURL:forSaveOperation:error: method on a background queue to perform the actual writing of the data to disk.If you override this method, it’s recommended that you first call the superclass implementation of the method (super). If you do not call super, you must do two things: Implement coordinated writing by using the NSFileCoordinator class. Call performAsynchronousFileAccessUsingBlock: to put the save operation on a background queue. The block parameter of this method should call writeContents:andAttributes:safelyToURL:forSaveOperation:error:.

Returns the file type to use for saving a document. The default implementation returns the current file type obtained from the fileType property. The default implementation of the saveToURL:forSaveOperation:completionHandler: method appends an extension to the file URL that is based on the file type. So if you want to move the document to a new type and extension, you can override this method to supply that file type.

Update the change counter by indicating the kind of change. Calling this method can affect the value returned by hasUnsavedChanges. You should not need to call method this if you access an NSUndoManager object from the undoManager property (or assign a custom one to it) and register changes with the undo manager.

Overridden to update the change count with reference to a change-count token passed in by UIKit. To get autosaving capabilities for your documents, you must implement change tracking. Typically you do this by using an NSUndoManager object (assigned to undoManager property) to register changes or by calling the updateChangeCount: method every time the user makes a change; UIKit then automatically determines whether there are unsaved changes and returns the proper value from hasUnsavedChanges. If you take neither of these approaches (and you want the autosaving feature), you must implement this method as well as changeCountTokenForSaveOperation: and hasUnsavedChanges.You implement the changeCountTokenForSaveOperation: method to return a change-count token that UIKit uses to encapsulate the history of document changes for a particular save operation. The token can be any object that represents the current change state of the document. This method is called at the start of the default implementation of the saveToURL:forSaveOperation:completionHandler: method. At the end of this default implementation, UIDocument calls this method (updateChangeCountWithToken:forSaveOperation:), passing in the change-count token. You implement this method to compare the token with the one returned earlier; by doing so, you can determine if the document has acquired new unsaved changes between the start and end of an asynchronous write operation. You can then return the proper value from your override of hasUnsavedChanges.

Sent when it is no longer safe to proceed without immediately handling the error. UIKit calls this method when it is no longer safe to proceed without immediately handling the error, such as when the application is being suspended. Subclasses that override this method must immediately end error handling (including dismissing any interactive user interface) and call finishedHandlingError:recovered: before returning. It is only necessary to override this method if you override handleError:userInteractionPermitted: without invoking the superclass implementation (super).

Ensures that document data is written safely to a specified location in the application sandbox. This method is responsible for writing the document file in a way that minimizes the danger of having the document data left in an inconsistent state because of an application crash, system crash, hardware failure, power outage, or similar reason. This default implementation of this method handles essential details that might change in future releases, so if you do override this method, you should be sure to invoke the superclass implementation (super) first.You don’t need to call this method directly unless you are overriding the saveToURL:forSaveOperation:completionHandler: method or you are calling the superclass implementation of the method.

Writes the document data to disk at the sandbox location indicated by a file URL. This method is called by the writeContents:toURL:forSaveOperation:originalContentsURL:error: to write the document data to disk. If you need access to the on-disk representation document while saving—for example, for doing incremental writes—you should override this method.