Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java


[Previous] [Class List] [Next]

NSDocumentController


Inherits from: NSObject
Package: com.apple.yellow.application


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
makeUntitledDocumentOfType
openDocumentWithContentsOfFile
openUntitledDocumentOfType
setShouldCreateUI
shouldCreateUI
Managing the Open panel
runModalOpenPanel
fileNamesFromRunningOpenPanel
currentDirectory
Closing documents
closeAllDocuments
reviewUnsavedDocumentsWithAlertTitle
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

Constructors


NSDocumentController

public NSDocumentController()

Static Methods



sharedDocumentController

public static NSDocumentController 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



URLsFromRunningOpenPanel

public NSArray URLsFromRunningOpenPanel()



closeAllDocuments

public boolean 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 when users decide to discard all changes.

currentDirectory

public String 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

public NSDocument currentDocument()

Returns the NSDocument object associated with the main window.

See Also: documentForFileName, documentForWindow, documents



displayNameForType

public String displayNameForType(String 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

public Class documentClassForType(String 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 null.

See Also: displayNameForType, fileExtensionsFromType, typeFromFileExtension



documentForFileName

public NSDocument documentForFileName(String 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 null if no document can be found.

See Also: documentForWindow, documents



documentForWindow

public NSDocument documentForWindow(NSWindow window)

Returns the NSDocument object whose window controller owns window. Returns null if window is null, 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

public 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

public NSArray fileExtensionsFromType(String 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

public 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 after initializaing the Open panel (which includes getting the starting directory with currentDirectory). Returns null if the user cancels the Open panel or makes no selection.

hasEditedDocuments

public boolean hasEditedDocuments()

Returns whether the receiver has any documents with unsaved changes.

See Also: documents



makeDocumentWithContentsOfFile

public NSDocument makeDocumentWithContentsOfFile(String aString, String 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 null 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.

See Also: makeUntitledDocumentOfType, openDocument



makeDocumentWithContentsOfURL

public NSDocument makeDocumentWithContentsOfURL(java.net.URL anURL, java.lang.String aString)



makeUntitledDocumentOfType

public NSDocument makeUntitledDocumentOfType(String type)

Creates and returns an NSDocument object for document type docType. The returned object is not retained. Returns null 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.

See Also: makeDocumentWithContentsOfFile, newDocument



newDocument

public void newDocument(Object 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 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

public void openDocument(Object 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, which actually creates the NSDocument objects.

See Also: fileNamesFromRunningOpenPanel, newDocument



openDocumentWithContentsOfFile

public NSDocument openDocumentWithContentsOfFile(String fileName, boolean flag)

Returns an NSDocument object created from the contents of the file fileName (an absolute path) and displays it if flag is true. The returned object is not retained, but is added to the receiver's list of managed documents. Returns null 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 true, the document is not displayed if shouldCreateUI returns false. This method invokes makeDocumentWithContentsOfFile to obtain the created NSDocument object.

See Also: openDocument, openUntitledDocumentOfType, setShouldCreateUI



openDocumentWithContentsOfURL

public NSDocument openDocumentWithContentsOfURL(java.net.URL anURL, boolean aBoolean)



openUntitledDocumentOfType

public NSDocument openUntitledDocumentOfType(String docType, boolean display)

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

See Also: newDocument, openDocumentWithContentsOfFile, setShouldCreateUI



reviewUnsavedDocumentsWithAlertTitle

public boolean reviewUnsavedDocumentsWithAlertTitle(String title, boolean 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 true) if they want to cancel the impending save-and-terminate operation. Returns true if the application is to quit and false 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 false).

runModalOpenPanel

public int runModalOpenPanel(NSOpenPanel openPanel, NSArray extensions)

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

saveAllDocuments

public void saveAllDocuments(Object 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

public void setShouldCreateUI(boolean 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 false for scripting or searching operations involving the document's data.

See Also: shouldCreateUI



shouldCreateUI

public boolean shouldCreateUI()

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

See Also: setShouldCreateUI



typeFromFileExtension

public String typeFromFileExtension(String fileExtension)

Returns the document type associated with files having extension fileExtension.

See Also: displayNameForType, fileExtensionsFromType



validateMenuItem

public boolean validateMenuItem(NSMenuItem anItem)

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


[Previous] [Next]