ADC Home > Reference Library > Reference > Cocoa > Design Guidelines > NSDocument Class Reference >

< Previous PageNext Page > Hide TOC

Deprecated NSDocument Methods

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

Deprecated in Mac 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 Mac 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
See Also
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 Mac 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
Declared In
NSDocument.h

fileName

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

- (NSString *)fileName

Availability
See Also
Related Sample Code
Declared In
NSDocument.h

fileWrapperRepresentationOfType:

Returns an NSFileWrapper object that represents the data of the receiver in a given type. (Deprecated in Mac 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
See Also
Declared In
NSDocument.h

initWithContentsOfFile:ofType:

Initializes and returns an NSDocument object. (Deprecated in Mac 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
Related Sample Code
Declared In
NSDocument.h

initWithContentsOfURL:ofType:

Initializes and returns an NSDocument object of a given document type. (Deprecated in Mac 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
Declared In
NSDocument.h

loadDataRepresentation:ofType:

Overridden by subclasses to load document data. (Deprecated in Mac 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
See Also
Declared In
NSDocument.h

loadFileWrapperRepresentation:ofType:

Loads document data from a given file wrapper. (Deprecated in Mac 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
See Also
Declared In
NSDocument.h

printShowingPrintPanel:

Overridden by subclasses to print the current document’s (the receiver’s) data. (Deprecated in Mac 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
See Also
Declared In
NSDocument.h

readFromFile:ofType:

Reads and loads document data of the given type from the given file. (Deprecated in Mac 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
See Also
Declared In
NSDocument.h

readFromURL:ofType:

Reads and loads document data. (Deprecated in Mac 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
Declared In
NSDocument.h

revertToSavedFromFile:ofType:

Reverts the receiver to the data stored in the file system. (Deprecated in Mac 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
See Also
Declared In
NSDocument.h

revertToSavedFromURL:ofType:

Reverts the receiver. (Deprecated in Mac 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
See Also
Declared In
NSDocument.h

runModalPageLayoutWithPrintInfo:

Runs the page layout modal panel with the receiver’s printing information object. (Deprecated in Mac 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
See Also
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 Mac 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
Declared In
NSDocument.h

setFileName:

Sets the file (filename and directory path) under which document data is saved. (Deprecated in Mac 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
See Also
Declared In
NSDocument.h

writeToFile:ofType:

Writes document data to a file. (Deprecated in Mac 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 “NSDocument Saving Behavior” for additional information about saving documents.

Availability
See Also
Declared In
NSDocument.h

writeToFile:ofType:originalFile:saveOperation:

Writes the receiver document’s contents to a file. (Deprecated in Mac 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 “NSDocument Saving Behavior” for additional information about saving documents.

Availability
Declared In
NSDocument.h

writeToURL:ofType:

Writes document data to a URL. (Deprecated in Mac 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
Declared In
NSDocument.h

writeWithBackupToFile:ofType:saveOperation:

This method is called by action methods to save document contents to a file. (Deprecated in Mac 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
Related Sample Code
Declared In
NSDocument.h

< Previous PageNext Page > Hide TOC

© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-01-06)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.