NSDocumentController Class Reference

Discussion

The open... methods automatically call addDocument:. This method is mostly provided for subclasses that want to know when documents arrive.

Discussion

A value of 0 indicates that periodic autosaving should not be done at all. NSDocumentController uses this number as the amount of time to wait between detecting that a document has unautosaved changes and sending the document an autosaveDocumentWithDelegate:didAutosaveSelector:contextInfo: message. The default value is 0.

Discussion

This is the action for the Clear menu command, but it can be invoked directly if necessary.

Discussion

Each NSDocument object is sent canCloseDocumentWithDelegate:shouldCloseSelector:contextInfo:, which, if the document is dirty, gives it a chance to refuse to close or to save itself first. This method may ask whether to save or to perform a save.

The didCloseAllSelector callback method is invoked with YES if all documents are closed, and NO otherwise. Pass the contextInfo object with the callback. The didCloseAllSelector callback method should have the following signature:

- (void)documentController:(NSDocumentController *)docController  didCloseAll: (BOOL)didCloseAll contextInfo:(void *)contextInfo

Discussion

The first valid directory from the following list is returned:

• The directory location where the current document was last saved

• The last directory visited in the Open panel

• The user’s home directory

Discussion

This method returns nil if it is called when its application is not active. This can occur during processing of a drag-and-drop operation, for example, in an implementation of readSelectionFromPasteboard:. In such a case, send the following message instead from an NSView subclass associated with the document:

[[[self window] windowController] document];

Discussion

The default implementation of this method returns the first Editor type declared by the CFBundleDocumentTypes array in the application's Info.plist, or returns nil if no Editor type is declared. You can override it to customize the type of document that is created when, for instance, the user chooses New in the File menu.

Discussion

For a document-based application, supported document types are specified in the Info.plist file by the CFBundleDocumentTypes array. Each document type is specified by a dictionary in this array, and is named by the CFBundleTypeName attribute. You can provide a descriptive, localized, representation of this name by providing a corresponding entry in the InfoPlist.strings file(s). For example, given an Info.plist file that contains the following fragment:

<dict>

    <key>CFBundleDocumentTypes</key>

    <array>

        <dict>

            <key>CFBundleTypeName</key>

            <string>BinaryFile</string>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>binary</string>

            </array>

you could provide a descriptive name by adding an entry in the InfoPlist.strings file:

BinaryFile = "Binary file format";

Discussion

Para

Discussion

The default implementation of this method returns information derived from the application's Info.plist property list file. You can override it to return the names of document classes that are dynamically loaded from plugins.

Discussion

The default implementation of this method queries each open document to find one whose URL matches, and returns the first one whose URL does match.

For backward binary compatibility with OS X v10.3 and earlier, the default implementation of this method instead invokes documentForFileName: if it is overridden and the URL uses the file: scheme.

Discussion

The default implementation of this method copies the file if specified, determines the type of the document, invokes makeDocumentForURL:withContentsOfURL:ofType:error: to instantiate it, sends the document setDisplayName: to name it if displayNameOrNil is not nil, invokes addDocument: to record its opening, and sends the document makeWindowControllers and showWindows messages.

The default implementation of this method uses the file coordination mechanism that was added to the Foundation framework in Mac OS 10.7. It passes the document to the NSFileCoordinator method addFilePresenter: right after invoking addDocument:. (The balancing invocation of the NSFileCoordinator method removeFilePresenter: is in the NSDocument method close.)

You can override this method to customize how documents are duplicated. It is invoked by the NSDocument method duplicateAndReturnError:. It may also be invoked from other places in AppKit.

Applications probably do not need to invoke this method directly.

Discussion

The first instance of NSDocumentController or any of its subclasses that is created becomes the shared instance.

Discussion

The URL is specified by absoluteDocumentURL, the type by typeName, and the other URL providing the contents by absoluteDocumentContentsURL. 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 instantiated. The default implementation of this method invokes documentClassForType: to find out the class of document to instantiate, allocates a document object, and initializes it by sending it an initForURL:withContentsOfURL:ofType:error: message.

Discussion

The URL is specified by absoluteURL and the document type by typeName. If not successful, the method returns nil after setting outError to point to an NSError that encapsulates the reason why the document could not be instantiated. The default implementation of this method invokes documentClassForType: to find out the class of document to instantiate, allocates a document object, and initializes it by sending it an initWithContentsOfURL:ofType:error: message.

For backward binary compatibility with OS X v10.3 and earlier, the default implementation of this method instead invokes makeDocumentWithContentsOfFile:ofType: if it is overridden and the URL uses the file: scheme.

Discussion

The document type is specified by typeName. If not successful, the method returns nil after setting outError to point to an NSError object that encapsulates the reason why a new untitled document could not be instantiated. The default implementation of this method invokes documentClassForType: to find out the class of document to instantiate, then allocates and initializes a document by sending it initWithType:error:.

For backward binary compatibility with OS X v10.3 and earlier, the default implementation of this method instead invokes makeUntitledDocumentOfType: if it is overridden.

Discussion

A value of 0 indicates that NSDocumentController will not attempt to add an Open Recent menu to your application's File menu, although NSDocumentController will not attempt to remove any preexisting Open Recent menu item. The default implementation returns a value that is subject to change and may or may not be derived from a setting made by the user in System Preferences.

Discussion

This method invokes openUntitledDocumentAndDisplay:error:.

Discussion

This method constructs a URL and calls noteNewRecentDocumentURL:. Subclasses might override this method to prevent certain documents or kinds of documents from getting into the list.

Discussion

NSDocument automatically calls this method when appropriate for NSDocument-based applications. Applications not based on NSDocument must also implement the application:openFile: method in the application delegate to handle requests from the Open Recent menu command. You can override this method in an NSDocument-based application to prevent certain kinds of documents from getting into the list (but you have to identify them by URL).

Discussion

The method adds the newly created objects to the list of NSDocument objects managed by the document controller. This method invokes openDocumentWithContentsOfURL:display:completionHandler:, which actually creates the NSDocument objects.

Discussion

The default implementation of this method checks to see if the document is already open or being opened, and if it is not determines the type of the document, invokes makeDocumentWithContentsOfURL:ofType:error: to instantiate it, invokes addDocument: to record its opening, and sends the document a makeWindowControllers message, and, if displayDocument is YES, showWindows. If the document is already open, the method just sends it a showWindows message if displayDocument is YES. If the relevant document class returns YES when sent canConcurrentlyReadDocumentsOfType: then the invocation of makeDocumentWithContentsOfURL:ofType:error: is done on a thread other than the main one, and when that has returned, the rest of the operation is done on the main thread.

The default implementation of this method uses the file coordination mechanism that was added to the Foundation framework in Mac OS 10.7. All of the work it does is one big coordinated read, and it passes the document to the NSFileCoordinator method addFilePresenter: right after invoking addDocument:. (The balancing invocation of the NSFileCoordinator method removeFilePresenter: is in the NSDocument method close.)

You can override this method to customize how documents are opened. Its implementation however is somewhat complex so unless your customization is to do additional work before invoking super, or to invoke super with a completion handler that does additional work before invoking the original completion handler, you should investigate overriding one of the methods that it invokes instead. If you do override this method you should investigate whether you should also override reopenDocumentForURL:withContentsOfURL:display:completionHandler: to apply the same customization. In either case, take care to always invoke the completion handler on the main thread.

You can invoke this method to open a document.

For backward binary compatibility with Mac OS 10.6 and earlier, the default implementation of this method invokes [self openDocumentWithContentsOfURL:url display:displayDocument error:&anError] if that method or the even older openDocumentWithContentsOfFile:display: method is overridden and this one is not, instead of invoking makeDocumentWithContentsOfURL:ofType:error: and all the rest.

Discussion

If not successful, the method returns nil after setting outError to point to an NSError that encapsulates the reason why a new untitled document could not be created.

The default implementation of this method invokes defaultType to determine the type of new document to create, invokes makeUntitledDocumentOfType:error: to create it, then invokes addDocument: to record its opening. If displayDocument is YES, it then sends the new document makeWindowControllers and showWindows messages.

For backward binary compatibility with OS X v10.3 and earlier, the default implementation of this method instead invokes openUntitledDocumentOfType:display: if it is overridden.

Discussion

Returns YES if error recovery was done, NO otherwise. This method does not return until the user dismisses the alert and, if the error has recovery options and a recovery delegate, the error's recovery delegate is sent an attemptRecoveryFromError:optionIndex: message.

The default NSDocumentController implementation of this method is equivalent to that of NSResponder while treating the application object as the next responder and forwarding error presentation messages to it. (The default NSDocument implementation of this method treats the shared NSDocumentController instance as the next responder and forwards these messages to it.) The default implementations of several NSDocumentController methods invoke this method.

The default implementation of this method invokes willPresentError: to give subclasses an opportunity to customize error presentation. You should not override this method but should instead override willPresentError:.

Discussion

When the user dismisses the alert and any recovery possible for the error and chosen by the user has been attempted, sends the message didPresentSelector to the specified delegate. The method selected by didPresentSelector must have the same signature as:

- (void)didPresentErrorWithRecovery:(BOOL)didRecover contextInfo:(void  *)contextInfo;

The default NSDocumentController implementation of this method is equivalent to that of NSResponder while treating the application object as the next responder and forwarding error presentation messages to it. (The default NSDocument implementation of this method treats the shared NSDocumentController instance as the next responder and forwards these messages to it.)

The default implementation of this method invokes willPresentError: to give subclasses an opportunity to customize error presentation. You should not override this method but should instead override willPresentError:.

Discussion

This method is not a good one to override since the internals of NSDocumentController do not generally use it.

Discussion

A document will automatically call removeDocument: when it closes. This method is mostly provided for subclasses that want to know when documents close.

Discussion

The default implementation of this method is very similar to openDocumentWithContentsOfURL:display:completionHandler:, the primary difference being that it invokes makeDocumentForURL:withContentsOfURL:ofType:error: instead of makeDocumentWithContentsOfURL:ofType:error:.

You can override this method to customize how documents are reopened during application launching by the restorable state mechanism introduced in Mac OS 10.7. Its implementation, however, is somewhat complex so, unless your customization is to do additional work before invoking super or invoke super with a completion handler that does additional work before invoking the original completion handler, you should investigate overriding one of the methods that it invokes instead.

Applications probably do not need to invoke this method directly.

For backward binary compatibility with Mac OS 10.6 and earlier, the default implementation of this method invokes [self reopenDocumentForURL:url withContentsOfURL:contentsURL error:&anError] if that method is overridden and this one is not, instead of invoking makeDocumentForURL:withContentsOfURL:ofType:error: and all the rest.

Discussion

Assigns delegate to the panel. Invokes didReviewAllSelector with YES if quit without saving is chosen or if there are no dirty documents, and NO otherwise. If the user selects the “Review Unsaved” option, closeAllDocumentsWithDelegate:didCloseAllSelector:contextInfo: is invoked. This method is invoked when the user chooses the Quit menu command, and also when the computer power is being turned off. Note that title is ignored. Pass the contextInfo object with the callback.

The didReviewAllSelector callback method should have the following signature:

- (void)documentController:(NSDocumentController *)docController  didReviewAll: (BOOL)didReviewAll contextInfo:(void *)contextInfo

Discussion

This method is invoked by the URLsFromRunningOpenPanel method. The extensions parameter may also contain encoded HFS file types as well as filename extensions.

Discussion

A value of 0 indicates that periodic autosaving should not be done at all. NSDocumentController uses this number as the amount of time to wait between detecting that a document has unautosaved changes and sending the document an autosaveDocumentWithDelegate:didAutosaveSelector:contextInfo: message. The default value is 0.

Discussion

The URL is represented by absoluteURL. If not successful, the method returns nil after setting outError to point to an NSError object that encapsulates the reason why the document type could not be determined, or the fact that the document type is unrecognized.

You can override this method to customize type determination for documents being opened.

Discussion

This method uses runModalOpenPanel:forTypes: to run the open panel. Returns the chosen files as an array of URLs. Returns nil if the user cancels the Open panel or makes no selection.

Discussion

Subclasses can override this method to perform additional validations. Subclasses should call super in their implementation for items they don’t handle themselves.

Discussion

The default implementation of this method merely returns the passed-in error. The returned error may simply be forwarded to the application object.

You can override this method to customize the presentation of errors by examining the passed-in error and, for example, returning more specific information. When you override this method always check the NSError object's domain and code to discriminate between errors whose presentation you want to customize and those you don't. For errors you don't want to customize, call the superclass implementation, passing the original error.