Deprecated NSDocumentController Methods

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

Deprecated in OS X v10.4

documentForFileName:

Returns the document object for the file in which the document data is stored. (Deprecated in OS X v10.4. Use documentForURL: instead.)

- (id)documentForFileName:(NSString *)fileName
Discussion

The fileName argument is a fully qualified path in the file system. Returns nil if no document can be found.

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

fileNamesFromRunningOpenPanel

Returns a selection of files chosen by the user in the Open panel. (Deprecated in OS X v10.4. Use URLsFromRunningOpenPanel instead.)

- (NSArray *)fileNamesFromRunningOpenPanel
Discussion

Each file in the returned NSArray is a fully qualified path to the file’s location in the file system. This method is called by openDocument:, and it calls runModalOpenPanel:forTypes: after initializing the Open panel (which includes getting the starting directory with currentDirectory). Returns nil if the user cancels the Open panel or makes no selection.

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

makeDocumentWithContentsOfFile:ofType:

Creates and returns a document object of a given document type from the contents of a file. (Deprecated in OS X v10.4. Use makeDocumentWithContentsOfURL:ofType:error: instead.)

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

Creates and returns an NSDocument object for document type docType from the contents of the file fileName, which must be a fully qualified path. The returned object is not retained. Returns nil if the NSDocument subclass for docType couldn’t be determined or if the object couldn’t be created. This method calls the NSDocument method initWithContentsOfFile:ofType: and is called by openDocumentWithContentsOfFile:display:.

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

makeDocumentWithContentsOfURL:ofType:

Creates and returns a document object for the given document type from the contents of a given URL. (Deprecated in OS X v10.4. Use makeDocumentWithContentsOfURL:ofType:error: instead.)

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

Creates and returns an NSDocument object for document type docType from the contents of aURL. The returned object is not retained. Returns nil if the NSDocument subclass for docType couldn’t be determined or if the object couldn’t be created. This method calls the NSDocument method initWithContentsOfURL:ofType: and is called by openDocumentWithContentsOfURL:display:.

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

makeUntitledDocumentOfType:

Creates and returns a document object for document type. (Deprecated in OS X v10.4. Use makeUntitledDocumentOfType:error: instead.)

- (id)makeUntitledDocumentOfType:(NSString *)type
Discussion

Creates and returns an NSDocument object for document type type. The returned object is not retained. Returns nil if the NSDocument subclass for type couldn’t be determined or if the object couldn’t be created. This method calls the NSDocument init method and is called by openUntitledDocumentOfType:display:.

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

openDocumentWithContentsOfFile:display:

Returns a document object created from the contents of a given file and optionally displays it. (Deprecated in OS X v10.4. Use openDocumentWithContentsOfURL:display:completionHandler: instead.)

- (id)openDocumentWithContentsOfFile:(NSString *)fileName display:(BOOL)flag
Discussion

Returns an NSDocument object created from the contents of the file fileName (an absolute path) and displays it if flag is YES. The returned object is not retained, but is added to the receiver’s list of managed documents. Returns nil if the object could not be created, typically because fileName does not point to a valid file or because there is no NSDocument subclass for the document type (as indicated by the file extension or HFS file type). Even if flag is YES, the document is not displayed if shouldCreateUI returns NO. This method calls makeDocumentWithContentsOfFile:ofType: to obtain the created NSDocument object. If you override this method, your implementation should be prepared to handle either YES or NO.

To handle an Open Documents Apple event, the Application Kit’s built-in Apple event handling automatically calls this method with the path to the file to open and a display argument.

Called with a display argument of YES instead of NO when a Print Documents Apple event is handled. This may have been handled differently in versions of OS X prior to version 10.3.

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

openDocumentWithContentsOfURL:display:

Returns a document object created from the contents of a given URL and optionally displays it. (Deprecated in OS X v10.4. Use openDocumentWithContentsOfURL:display:completionHandler: instead.)

- (id)openDocumentWithContentsOfURL:(NSURL *)aURL display:(BOOL)flag
Discussion

Returns an NSDocument object created from the contents of aURL and displays it if flag is YES. The returned object is not retained, but is added to the receiver’s list of managed documents. Returns nil if the object could not be created, typically because aURL does not point to a valid location or because there is no NSDocument subclass for the document type. Even if flag is YES, the document is not displayed if shouldCreateUI returns NO. This method calls makeDocumentWithContentsOfURL:ofType: to obtain the created NSDocument object.

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

openUntitledDocumentOfType:display:

Returns a document object instantiated from the subclass of the given document type and optionally displays it. (Deprecated in OS X v10.4. Use openUntitledDocumentAndDisplay:error: with defaultType instead.)

- (id)openUntitledDocumentOfType:(NSString *)docType display:(BOOL)display
Discussion

Returns an NSDocument object instantiated from the NSDocument subclass required by document type docType and displays it if flag is YES. The returned object is not retained, but is added to the receiver’s list of managed documents. Returns nil if the object could not be created, typically because no NSDocument subclass could be found for docType. Even if flag is YES, the document is not displayed if shouldCreateUI returns NO. This method calls makeUntitledDocumentOfType: to obtain the created NSDocument object.

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

setShouldCreateUI:

Sets whether the window controllers of a document should be created when the document is created. (Deprecated in OS X v10.4. Use the display parameter of openUntitledDocumentAndDisplay:error: or openDocumentWithContentsOfURL:display:completionHandler: instead.)

- (void)setShouldCreateUI:(BOOL)flag
Discussion

Sets whether the window controllers (NSWindowController instances) of a document should be created when the document is created. When a window controller is created, it loads the nib file containing the window it manages. Often flag is set to NO for scripting or searching operations involving the document’s data.

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

shouldCreateUI

Returns a Boolean value that indicates whether the window controllers of a document should be created when the document is created. (Deprecated in OS X v10.4. Use the display parameter of openUntitledDocumentAndDisplay:error: or openDocumentWithContentsOfURL:display:completionHandler: instead.)

- (BOOL)shouldCreateUI
Return Value

A Boolean value that indicates whether the window controllers (NSWindowController instances) of a document should be created when the document is created.

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

Deprecated in OS X v10.5

fileExtensionsFromType:

Returns the allowable file extensions for the given document type. (Deprecated in OS X v10.5. Use the NSDocument method fileNameExtensionForType:saveOperation: instead.)

- (NSArray *)fileExtensionsFromType:(NSString *)documentTypeName
Parameters
documentTypeName

The name of a document type, specified by CFBundleTypeName in the application’s Info.plist file.

Return Value

The allowable file extensions (as NSString objects) for documentTypeName.

Discussion

Type extensions are specified by the CFBundleTypeExtensions array for the given type in the Info.plist file.

The first string in the returned array is typically the most common extension. The array may also contain encoded HFS file types as will as filename extensions.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.5.
Declared In
NSDocumentController.h

typeFromFileExtension:

Returns the document type associated with files having extension fileExtensionOrHFSFileType. (Deprecated in OS X v10.5. Use typeForContentsOfURL:error: instead.)

- (NSString *)typeFromFileExtension:(NSString *)fileExtensionOrHFSFileType
Discussion

The fileExtensionOrHFSFileType parameter may also be an encoded HFS file type, as well as a filename extension.

This method only works when passed a file name extension used in a CFBundleDocumentTypes entry that does not have an LSItemContentTypes subentry.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.5.
Declared In
NSDocumentController.h

Deprecated in OS X v10.7

openDocumentWithContentsOfURL:display:error:

Opens a document located by the given URL presents its user interface if requested, and returns the document if successful. (Deprecated in OS X v10.7. Use openDocumentWithContentsOfURL:display:completionHandler: instead.)

- (id)openDocumentWithContentsOfURL:(NSURL *)absoluteURL display:(BOOL)displayDocument error:(NSError **)outError
Discussion

If not successful, the method returns nil after setting outError to point to an NSError object that encapsulates the reason why the document could not be opened.

The default implementation of this method checks to see if the document is already open according to documentForURL:, and if it is not open determines the type of the document, calls makeDocumentWithContentsOfURL:ofType:error: to instantiate it, then calls addDocument: to record its opening, and sends the document makeWindowControllers and showWindows messages if displayDocument is YES. If the document is already open it is just sent a showWindows message if displayDocument is YES.

Availability
  • Available in OS X v10.4 and later.
  • Deprecated in OS X v10.7.
Related Sample Code
Declared In
NSDocumentController.h

reopenDocumentForURL:withContentsOfURL:error:

Reopens an autosaved document located by a URL, by reading the contents for the document from another URL, presents its user interface, and returns YES if successful. (Deprecated in OS X v10.7. Use reopenDocumentForURL:withContentsOfURL:display:completionHandler: instead.)

- (BOOL)reopenDocumentForURL:(NSURL *)absoluteDocumentURL withContentsOfURL:(NSURL *)absoluteDocumentContentsURL error:(NSError **)outError
Discussion

The document is located by absoluteDocumentURL and the contents are read from absoluteDocumentContentsURL. If not successful, the method returns NO after setting outError to point to an NSError object that encapsulates the reason why the document could not be reopened.

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