[Previous] [Class List] [Next]

NSDocumentController


Inherits from: NSObject
Conforms to: NSObject
(NSObject)
Declared in: AppKit/NSDocumentController.h




Class Description


An NSDocumentController object manages an application's documents. As the first-responder target of New and Open menu commands, it creates and opens documents and tracks them throughout a session of the application.When opening documents, an NSDocumentController runs and manages the modal Open panel. As the application delegate, it saves and closes documents when applications are terminated and it responds to NSWorkspace methods when documents are opened or printed from the workspace. NSDocumentControllers also maintain and manage the mappings of document types, extensions, and NSDocument subclasses as specified in the NSTypes property loaded from the custom info property list (CustomInfo.plist). One instance of NSDocumentController is shared among processes.

You can use various NSDocumentController methods to get a list of the current documents, get the current document (which is the document whose window is currently key), get documents based on a given file name or window, and to find out about a document's extension, type, display name, and document class.

A document-based application can use the default NSDocumentController instance provided by the Application Kit, because this instance not only creates and manages documents, but acts as application controller. Typically, however, applications will require their own custom subclasses of NSDocumentController to implement behavior not provided by default, such as loading About panels and managing user preferences.

For more on the architecture of document-based applications, and the procedure for implementing, see the concepts ""Document-Based Application Architecture"" and ""Implementing a Document-Based Application"", currently in the NSDocument class description.


Method Types


Obtaining the shared instance
+ sharedDocumentController
Creating and opening documents
- makeDocumentWithContentsOfFile:ofType:
- makeUntitledDocumentOfType:
- openDocumentWithContentsOfFile:display:
- openUntitledDocumentOfType:display:
- setShouldCreateUI:
- shouldCreateUI
Managing the Open panel
- runModalOpenPanel:forTypes:
- fileNamesFromRunningOpenPanel
- currentDirectory
Closing documents
- closeAllDocuments
- reviewUnsavedDocumentsWithAlertTitle:cancellable:
Responding to action messages
- newDocument:
- openDocument:
- saveAllDocuments:
Managing documents
- documents
- currentDocument
- documentClassForType:
- documentForFileName:
- documentForWindow:
- hasEditedDocuments
Managing document types
- displayNameForType:
- fileExtensionsFromType:
- typeFromFileExtension:
Validating menu items
- validateMenuItem:

Class Methods



sharedDocumentController

+ (id)sharedDocumentController

Returns the shared NSDocumentController instance. If one doesn't exist yet, it is created. Initialization reads in the document types from the NSTypes property list (in CustomInfo.plist), registers the instance for NSWorkspaceWillPowerOffNotifications, and turns on the flag indicating that document user interfaces should be visible. You should always obtain your application's NSDocumentController using this method.

See Also: - setShouldCreateUI:




Instance Methods



closeAllDocuments

- (BOOL)closeAllDocuments

Attempts to close all documents owned by the receiver and returns whether all documents were closed. It does not ask users whether they want to save documents. This method is invoked in reviewUnsavedDocumentsWithAlertTitle:cancellable: when users decide to discard all changes.

currentDirectory

- (NSString *)currentDirectory

Returns the directory path to be used as the starting point in the Open panel. The first valid directory from the following list is returned:

See Also: - documentForFileName:



currentDocument

- (id)currentDocument

Returns the NSDocument object associated with the main window.

See Also: - documentForFileName:, - documentForWindow:, - documents



displayNameForType:

- (NSString *)displayNameForType:(NSString *)docType

Returns the descriptive name for the document type (docType), which is often part of the document's window title. This returned value is associated with the NSTypeName key in the NSType property list.If there is no such value, docType is returned.

See Also: - fileExtensionsFromType:, - typeFromFileExtension:



documentClassForType:

- (Class)documentClassForType:(NSString *)docType

Returns the NSDocument subclass associated with document type docType. The document type must be one the document can read. If the class cannot be found, returns nil.

See Also: - displayNameForType:, - fileExtensionsFromType:, - typeFromFileExtension:



documentForFileName:

- (id)documentForFileName:(NSString *)fileName

Returns the NSDocument object for the file in which the document data is stored. The fileName argument is a fully qualified path in the file system. Returns nil if no document can be found.

See Also: - documentForWindow:, - documents



documentForWindow:

- (id)documentForWindow:(NSWindow *)window

Returns the NSDocument object whose window controller owns window. Returns nil if window is nil, if window has no window controller, or if the window controller does not have an association with an NSDocument.

See Also: - currentDocument, - documentForFileName:, - documents



documents

- (NSArray *)documents

Returns the NSDocument objects managed by the receiver. If there are currently no documents, returns an empty NSArray.

See Also: - currentDocument, - documentForFileName:, - documentForWindow:



fileExtensionsFromType:

- (NSArray *)fileExtensionsFromType:(NSString *)docType

Returns the allowable file extensions (as NSString objects) for document type docType. The first string in the returned NSArray is typically the most common extension.

See Also: - displayNameForType:, - typeFromFileExtension:



fileNamesFromRunningOpenPanel

- (NSArray *)fileNamesFromRunningOpenPanel

Returns a selection of files chosen by the user in the Open panel. Each file in the returned NSArray is a fully qualified path to the file's location in the file system. This method is invoked by openDocument: and it invokes runModalOpenPanel:forTypes: after initializaing the Open panel (which includes getting the starting directory with currentDirectory). Returns nil if the user cancels the Open panel or makes no selection.

hasEditedDocuments

- (BOOL)hasEditedDocuments

Returns whether the receiver has any documents with unsaved changes.

See Also: - documents



makeDocumentWithContentsOfFile:ofType:

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

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 invokes NSDocument's initWithContentsOfFile:ofType: and is invoked by openDocumentWithContentsOfFile:display:.

See Also: - makeUntitledDocumentOfType:, - openDocument:



makeUntitledDocumentOfType:

- (id)makeUntitledDocumentOfType:(NSString *)type

Creates and returns an NSDocument object for document type docType. 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 invokes NSDocument's init and is invoked by openUntitledDocumentOfType:display:.

See Also: - makeDocumentWithContentsOfFile:ofType:, - newDocument:



newDocument:

- (void)newDocument:(id)sender

An action method invoked the New menu command, it creates a new NSDocument object and adds it to the list of such objects managed by the receiver. It invokes openUntitledDocumentOfType:display: with the document type (first argument) being the first one specified in the NSType property (defined in CustomInfo.plist); the document type determines the NSDocument sublcass used to instantiate the document object.

See Also: openDocument:



openDocument:

- (void)openDocument:(id)sender

An action method invoked the Open menu command, it runs the modal Open panel and, based on the selected filenames, creates one or more NSDocument object from the contents of the files; it adds these objects to the list of NSDocument objects managed by the receiver. This method invokes openDocumentWithContentsOfFile:display:, which actually creates the NSDocument objects.

See Also: - fileNamesFromRunningOpenPanel, - newDocument:



openDocumentWithContentsOfFile:display:

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

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 sublcass for the document type (as indicated by the file extension). Even if flag is YES, the document is not displayed if shouldCreateUI returns NO. This method invokes makeDocumentWithContentsOfFile:ofType: to obtain the created NSDocument object.

See Also: - openDocument:, - openUntitledDocumentOfType:display:, - setShouldCreateUI:



openUntitledDocumentOfType:display:

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

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 sublcass could be found for docType. Even if flag is YES, the document is not displayed if shouldCreateUI returns NO. This method invokes makeUntitledDocumentOfType: to obtain the created NSDocument object.

See Also: - newDocument:, - openDocumentWithContentsOfFile:display:, - setShouldCreateUI:



reviewUnsavedDocumentsWithAlertTitle:cancellable:

- (BOOL)reviewUnsavedDocumentsWithAlertTitle:(NSString *)title cancellable:(BOOL)flag

Displays an attention panel (a dialog) asking users if they want to review unsaved documents, quit regardless of unsaved documents, or (if flag is YES) if they want to cancel the impending save-and-terminate operation. Returns YES if the application is to quit and NO if otherwise (used only when the application is terminating). If the user selects the Review Unsaved option, closeAllDocuments is invoked. This method is invoked when users choose the Quit menu command and when the computer power is being turned off (in which case, flag is NO).

runModalOpenPanel:forTypes:

- (int)runModalOpenPanel:(NSOpenPanel *)openPanel forTypes:(NSArray *)extensions

Invokes NSOpenPanel's runModalForTypes: passing the file extensions associated with a document type. This method is invoked by the fileNamesFromRunningOpenPanel method.

saveAllDocuments:

- (void)saveAllDocuments:(id)sender

As the action method invoked by the Save All command, saves all open documents of the application that need to be saved.

See Also: saveDocument: (NSDocument)



setShouldCreateUI:

- (void)setShouldCreateUI:(BOOL)flag

Sets whether the window controllers (NSWindowControllers) 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.

See Also: - shouldCreateUI



shouldCreateUI

- (BOOL)shouldCreateUI

Returns whether the window controllers (NSWindowControllers) of a document should be created when the document is created.

See Also: - setShouldCreateUI:



typeFromFileExtension:

- (NSString *)typeFromFileExtension:(NSString *)fileExtension

Returns the document type associated with files having extension fileExtension.

See Also: - displayNameForType:, - fileExtensionsFromType:



validateMenuItem:

- (BOOL)validateMenuItem:(NSMenuItem *)anItem

Validates menu item anItem, returning YES if it should be enabled, NO otherwise. As implemented, if anItem is the Save All menu item, returns YES if there are any edited documents. Subclasses can override this method to perform additional validations.


[Previous] [Next]