Deprecated NSDocument Methods

A method identified as deprecated has been superseded and may become unsupported in the future.

Available in OS X v10.0 through OS X v10.3

canCloseDocument

This method is no longer supported. (Available in OS X v10.0 through OS X v10.3. Use canCloseDocumentWithDelegate:shouldCloseSelector:contextInfo: instead.)

- (BOOL)canCloseDocument
Availability
  • Available in OS X v10.0 through OS X v10.3.
Declared In
NSDocument.h

fileNameFromRunningSavePanelForSaveOperation:

Returns the filename entered into the Save panel. (Available in OS X v10.0 through OS X v10.3. Use saveDocumentWithDelegate:didSaveSelector:contextInfo: instead.)

- (NSString *)fileNameFromRunningSavePanelForSaveOperation:(NSSaveOperationType)saveOperation
Availability
  • Available in OS X v10.0 through OS X v10.3.
Declared In
NSDocument.h

shouldCloseWindowController:

Gives the user an opportunity to save the document. (Available in OS X v10.0 through OS X v10.3. Use shouldCloseWindowController:delegate:shouldCloseSelector:contextInfo: instead.)

- (BOOL)shouldCloseWindowController:(NSWindowController *)windowController
Discussion

If closing the windowController would cause the receiver to be closed, invokes canCloseDocumentWithDelegate:shouldCloseSelector:contextInfo: to display a Save panel and give the user an opportunity to save the document. Returns the return value of canCloseDocumentWithDelegate:shouldCloseSelector:contextInfo:. Note that the receiver doesn’t close until its window controller closes.

Availability
  • Available in OS X v10.0 through OS X v10.3.
Declared In
NSDocument.h

validateMenuItem:

Validates the Revert menu item and items selected from the Save panel’s pop-up list of writable document types items. (Available in OS X v10.0 through OS X v10.3. Use validateUserInterfaceItem: instead.)

- (BOOL)validateMenuItem:(NSMenuItem *)anItem
Discussion

Returns YES if anItem should be enabled, NO otherwise. Returns YES for Revert if the document has been edited and a file exists for the document. Returns YES for an item representing a writable type if, during a Save or Save As operation, it is a native type for the document. Subclasses can override this method to perform additional validations.

Availability
  • Available in OS X v10.0 through OS X v10.3.
Declared In
NSDocument.h

Deprecated in OS X v10.4

dataRepresentationOfType:

A primitive method overridden by subclasses to return a data object that represents the data of the receiver in a given type. (Deprecated in OS X v10.4. Use dataOfType:error: instead.)

- (NSData *)dataRepresentationOfType:(NSString *)aType
Discussion

A primitive method overridden by subclasses to return a data object that represents the data of the receiver in a given type (aType). The default implementation raises an NSInternalInconsistencyException. This method is invoked by the default implementation of fileWrapperRepresentationOfType:.

aType is the type name corresponding to the value of the CFBundleTypeName entry in the document type’s Info.plist dictionary.

Here is a typical implementation:

//Document type name
NSString *MyDocumentType = @"Rich Text Format (RTF) document";
 
...
 
- (NSData *)dataRepresentationOfType:(NSString *)aType {
    NSAssert([aType isEqualToString:MyDocumentType], @"Unknown  type");
    return [textView RTFFromRange:NSMakeRange(0, [[textView textStorage]  length])];
}
Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

fileAttributesToWriteToFile:ofType:saveOperation:

Returns the file attributes that should be written to the named document file of the specified type. (Deprecated in OS X v10.4. Use fileAttributesToWriteToURL:ofType:forSaveOperation:originalContentsURL:error: instead.)

- (NSDictionary *)fileAttributesToWriteToFile:(NSString *)fullDocumentPath ofType:(NSString *)docType saveOperation:(NSSaveOperationType)saveOperationType
Discussion

Returns the file attributes that should be written to the named document file of the specified type docType, as part of a particular saveOperationType. The set of valid file attributes is a subset of those understood by the NSFileManager class.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

fileName

Returns the filename (as a fully qualified path) under which the receiver has been saved. (Deprecated in OS X v10.4. Use fileURL instead.)

- (NSString *)fileName
Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

fileWrapperRepresentationOfType:

Returns an NSFileWrapper object that represents the data of the receiver in a given type. (Deprecated in OS X v10.4. Use fileWrapperOfType:error: instead.)

- (NSFileWrapper *)fileWrapperRepresentationOfType:(NSString *)aType
Discussion

Returns an NSFileWrapper object that represents the data of the receiver in a given type (aType). This method invokes dataRepresentationOfType: to get the data object from which to create a plain-file file wrapper. Subclasses can override this method if dataRepresentationOfType: is not adequate for their needs. This method is invoked by the default implementation of writeToFile:ofType:.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

initWithContentsOfFile:ofType:

Initializes and returns an NSDocument object. (Deprecated in OS X v10.4. Use initWithContentsOfURL:ofType:error: instead.)

- (id)initWithContentsOfFile:(NSString *)fileName ofType:(NSString *)docType
Discussion

Initializes and returns an NSDocument object of document type docType containing data stored in the file fileName. In opening the file, invokes the readFromFile:ofType: method. If the document successfully opens the file, it calls setFileName: and setFileType: with fileName and docType, respectively, as arguments. If the file cannot be opened, or the document is unable to load the contents of the file, this method returns nil. This initializer is typically invoked by the NSDocumentController method makeDocumentWithContentsOfFile:ofType:.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

initWithContentsOfURL:ofType:

Initializes and returns an NSDocument object of a given document type. (Deprecated in OS X v10.4. Use initWithContentsOfURL:ofType:error: instead.)

- (id)initWithContentsOfURL:(NSURL *)aURL ofType:(NSString *)docType
Discussion

Initializes and returns an NSDocument object of document type docType containing data stored at aURL. In opening the location, invokes the readFromURL:ofType: method. If the document successfully opens the location, it calls setFileName: and setFileType: with the location’s path and docType, respectively, as arguments. If the location cannot be opened, or the document is unable to load the contents of the location, this method returns nil. This initializer is typically invoked by the NSDocumentController method makeDocumentWithContentsOfURL:ofType:.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

loadDataRepresentation:ofType:

Overridden by subclasses to load document data. (Deprecated in OS X v10.4. Use readFromData:ofType:error: instead.)

- (BOOL)loadDataRepresentation:(NSData *)docData ofType:(NSString *)docType
Discussion

Overridden by subclasses to load document data (docData) of type docType into the receiver, display it in windows, and return whether the operation was successful. This method is typically invoked by loadFileWrapperRepresentation:ofType: after an NSData object is created from the contents of the file wrapper (which can include directories). The default implementation raises an NSInternalInconsistencyException. Subclasses must override this method unless they override readFromFile:ofType: or loadFileWrapperRepresentation:ofType: to do specialized reading and loading of document data.

The docType argument is the type name corresponding to the value of the CFBundleTypeName entry in the document type’s Info.plist dictionary.

Here is an example implementation:

//Document type name
NSString *MyDocumentType = @"Rich Text Format (RTF) document";
 
...
 
- (BOOL)loadDataRepresentation:(NSData *)data ofType:(NSString *)aType  {
    NSAssert([aType isEqualToString: MyDocumentType], @"Unknown  type");
    fileContents = [data copyWithZone:[self zone]];
    return YES;
}
Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

loadFileWrapperRepresentation:ofType:

Loads document data from a given file wrapper. (Deprecated in OS X v10.4. Use readFromFileWrapper:ofType:error: instead.)

- (BOOL)loadFileWrapperRepresentation:(NSFileWrapper *)wrapper ofType:(NSString *)docType
Discussion

Loads document data in file wrapper wrapper of type docType into the receiver, displays it in windows, and returns whether the operation was successful. If wrapper is a simple file, it invokes loadDataRepresentation:ofType: to load the data. If wrapper is a directory, it returns NO by default; subclasses can override to handle file wrappers that are directories. This method is typically invoked by readFromFile:ofType: after it creates an NSData object from the contents of the file.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

printShowingPrintPanel:

Overridden by subclasses to print the current document’s (the receiver’s) data. (Deprecated in OS X v10.4. Use printDocumentWithSettings:showPrintPanel:delegate:didPrintSelector:contextInfo: instead.)

- (void)printShowingPrintPanel:(BOOL)flag
Discussion

Overridden by subclasses to print the current document’s (the receiver’s) data; if flag is YES, the implementation should first display the Print panel. This method is typically invoked by printDocument: with an argument of YES. The default implementation does nothing. If there is any printing information other than that encoded in the receiver’s NSPrintInfo object, subclasses should get it here.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

readFromFile:ofType:

Reads and loads document data of the given type from the given file. (Deprecated in OS X v10.4. Use readFromURL:ofType:error: instead.)

- (BOOL)readFromFile:(NSString *)fileName ofType:(NSString *)docType
Discussion

Reads and loads document data of type docType from the file fileName, returning whether the operation was successful. This method invokes loadDataRepresentation:ofType: and is invoked when the receiver is first created and initialized by initWithContentsOfFile:ofType:. It uses NSData initWithContentsOfFile: to get the document data.

This method is one of the location-based primitives. Subclasses can override this method instead of overriding loadDataRepresentation:ofType: to read and load document data. Subclasses that handle file packages such as RTFD or that treat locations of files as anything other than paths should override this method. Override implementations of this method can filter the document data using NSPasteboard or other filtering services.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

readFromURL:ofType:

Reads and loads document data. (Deprecated in OS X v10.4. Use readFromURL:ofType:error: instead.)

- (BOOL)readFromURL:(NSURL *)aURL ofType:(NSString *)docType
Discussion

Reads and loads document data of type docType from the URL aURL, returning whether the operation was successful. This method only supports URLs of the file: scheme and calls readFromFile:ofType:.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

revertToSavedFromFile:ofType:

Reverts the receiver to the data stored in the file system. (Deprecated in OS X v10.4. Use revertToContentsOfURL:ofType:error: instead.)

- (BOOL)revertToSavedFromFile:(NSString *)fileName ofType:(NSString *)type
Discussion

Reverts the receiver to the data stored in the file system in file named fileName of file type type. Invokes readFromFile:ofType: and returns whether that method successfully read the file and processed the document data.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

revertToSavedFromURL:ofType:

Reverts the receiver. (Deprecated in OS X v10.4. Use revertToContentsOfURL:ofType:error: instead.)

- (BOOL)revertToSavedFromURL:(NSURL *)aURL ofType:(NSString *)type
Discussion

Reverts the receiver to the data stored at aURL of type type. Invokes readFromURL:ofType: and returns whether that method successfully read the file and processed the document data.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

runModalPageLayoutWithPrintInfo:

Runs the page layout modal panel with the receiver’s printing information object. (Deprecated in OS X v10.4. Use runModalPageLayoutWithPrintInfo:delegate:didRunSelector:contextInfo: instead.)

- (NSInteger)runModalPageLayoutWithPrintInfo:(NSPrintInfo *)printInfo
Discussion

Runs the page layout modal panel with the receiver’s printing information object (printInfo) as argument and returns the result constant (indicating the button pressed by the user). To run as sheet on the receiver’s document window, use runModalPageLayoutWithPrintInfo:delegate:didRunSelector:contextInfo: instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

saveToFile:saveOperation:delegate:didSaveSelector:contextInfo:

Called after the user has been given the opportunity to select a destination through the modal Save panel. (Deprecated in OS X v10.4. Use saveToURL:ofType:forSaveOperation:delegate:didSaveSelector:contextInfo: instead.)

- (void)saveToFile:(NSString *)fileName saveOperation:(NSSaveOperationType)saveOperation delegate:(id)delegate didSaveSelector:(SEL)didSaveSelector contextInfo:(void *)contextInfo
Discussion

Called after the user has been given the opportunity to select a destination through the modal Save panel presented by runModalSavePanelForSaveOperation:delegate:didSaveSelector:contextInfo:. The delegate is assigned to the Save panel. If fileName is non-nil, this method writes the document to fileName, sets the document’s file location and document type (if a native type), and clears the document’s edited status. didSaveSelector gets called with YES if the document is saved successfully, and NO otherwise. The saveOperation is one of the constants in “Constants.” Pass contextInfo with the callback.

The didSaveSelector callback method should have the following signature:

- (void)document:(NSDocument *)doc didSave:(BOOL)didSave contextInfo:(void  *)contextInfo
Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

setFileName:

Sets the file (filename and directory path) under which document data is saved. (Deprecated in OS X v10.4. Use setFileURL: instead.)

- (void)setFileName:(NSString *)fileName
Discussion

Sets the file (filename and directory path) under which document data is saved to fileName. As a side effect, synchronizes the titles of the document’s windows with the new name or location. A document’s filename is automatically set when it is saved as a new document (Save) and when an existing document is saved under a different filename or path (Save As). The Finder also keeps track of open documents and their associated files. When a user moves or renames a file in the Finder that corresponds to an open document, the Finder calls setFileName: with the new filename.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
See Also
Declared In
NSDocument.h

writeToFile:ofType:

Writes document data to a file. (Deprecated in OS X v10.4. Use writeToURL:ofType:error: instead.)

- (BOOL)writeToFile:(NSString *)fileName ofType:(NSString *)docType
Discussion

Writes document data of type docType to the file fileName, returning whether the operation was successful. This method invokes dataRepresentationOfType: and is indirectly invoked whenever the document file is saved. It uses the NSData method writeToFile:atomically: to write to the file.

This method is one of the location-based primitives. Subclasses can override this method instead of overriding dataRepresentationOfType: to write document data to the file system as an NSData object after creating that object from internal data structures. Subclasses that handle file packages such as RTFD or that treat locations of files as anything other than paths should override this method. Override implementations of this method should ensure that they filter document data appropriately using NSPasteboard filtering services.

See “Document Saving Behavior” for additional information about saving documents.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

writeToFile:ofType:originalFile:saveOperation:

Writes the receiver document’s contents to a file. (Deprecated in OS X v10.4. Use writeToURL:ofType:forSaveOperation:originalContentsURL:error: instead.)

- (BOOL)writeToFile:(NSString *)fullDocumentPath ofType:(NSString *)docType originalFile:(NSString *)fullOriginalDocumentPath saveOperation:(NSSaveOperationType)saveOperationType
Discussion

This method is called from writeWithBackupToFile:ofType:saveOperation: to actually write the file of type docType to fullDocumentPath. fullOriginalDocumentPath is the path to the original file if there is one and nil otherwise. The default implementation simply calls writeToFile:ofType:. You should not need to call this method directly, but subclasses that need access to the previously saved copy of their document while saving the new one can override this method. The saveOperationType argument is one of the constants listed in “Constants.”

See “Document Saving Behavior” for additional information about saving documents.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

writeToURL:ofType:

Writes document data to a URL. (Deprecated in OS X v10.4. Use writeToURL:ofType:error: instead.)

- (BOOL)writeToURL:(NSURL *)aURL ofType:(NSString *)docType
Discussion

Writes document data of type docType to the URL aURL, returning whether the operation was successful. This method only supports URLs of the file: scheme and calls writeToFile:ofType:.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

writeWithBackupToFile:ofType:saveOperation:

This method is called by action methods to save document contents to a file. (Deprecated in OS X v10.4. Use writeSafelyToURL:ofType:forSaveOperation:error: instead.)

- (BOOL)writeWithBackupToFile:(NSString *)fullDocumentPath ofType:(NSString *)docType saveOperation:(NSSaveOperationType)saveOperationType
Discussion

This method is called by action methods like saveDocument:, saveDocumentAs:, and saveDocumentTo:. It is responsible for handling backup of the existing file, if any, and removal of that backup if keepBackupFile returns NO. In between those two things, it calls writeToFile:ofType:originalFile:saveOperation: to write the document of type docType to fullDocumentPath. You should never need to call writeWithBackupToFile:ofType:saveOperation:, but subclasses that want to change the way the backup works can override it. The saveOperationType argument is one of the constants listed in “Constants.”

If you override this method, you should invoke fileAttributesToWriteToFile:ofType:saveOperation: and set the variables returned from this method when writing fullDocumentPath. NSFileManager changeFileAttributes:atPath: can be used to do this.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSDocument.h

Deprecated in OS X v10.7

saveToURL:ofType:forSaveOperation:error:

Saves the contents of the document to a file or file package located by a URL, formatted to a specified type, for a particular kind of save operation, and returns YES if successful. (Deprecated in OS X v10.7. Use saveToURL:ofType:forSaveOperation:completionHandler: instead.)

- (BOOL)saveToURL:(NSURL *)absoluteURL ofType:(NSString *)typeName forSaveOperation:(NSSaveOperationType)saveOperation error:(NSError **)outError
Parameters
absoluteURL

The location of the file or file package to which the document contents are saved.

typeName

The string that identifies the document type.

saveOperation

The type of save operation.

outError

On return, if the document contents could not be saved, a pointer to an error object that encapsulates the reason they could not be saved.

Return Value

YES if the document contents were successfully saved; otherwise, NO.

Discussion

You can override this method to do things that need to be done before or after any save operation. If you override this method, you must call super at some point in your implementation.

Availability
  • Available in OS X v10.4 and later.
  • Deprecated in OS X v10.7.
Declared In
NSDocument.h