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

Table of Contents

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


Constructors
NSDocumentController
Obtaining the shared instance
sharedDocumentController
Creating and opening documents
makeDocumentWithContentsOfFile
makeDocumentWithContentsOfURL
makeUntitledDocumentOfType
openDocumentWithContentsOfFile
openDocumentWithContentsOfURL
openUntitledDocumentOfType
setShouldCreateUI
shouldCreateUI
Managing the Open panel
runModalOpenPanel
fileNamesFromRunningOpenPanel
currentDirectory
URLsFromRunningOpenPanel
Closing documents
closeAllDocuments
reviewUnsavedDocumentsWithAlertTitle
Responding to action messages
newDocument
openDocument
saveAllDocuments
Managing documents
documents
addDocument
clearRecentDocuments
currentDocument
documentClassForType
documentForFileName
documentForWindow
hasEditedDocuments
noteNewRecentDocumentURL
recentDocumentURLs
removeDocument
Managing document types
displayNameForType
fileExtensionsFromType
typeFromFileExtension
Validating menu items
validateMenuItem


Constructors



NSDocumentController

public NSDocumentController()

Description forthcoming.


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 WorkspaceWillPowerOffNotifications, 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



addDocument

public void addDocument(NSDocument document)

Adds document to the list of open documents. The open... methods automatically call addDocument. This method is mostly provided for subclassers that want to know when documents arrive.

clearRecentDocuments

public void clearRecentDocuments(Object sender)

Empties the recent documents list for the application. This is the action for the Clear Menu command, but it can be invoked directly if necessary.

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 TypeName 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 SString 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 initializing 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. Returns null if the NSDocument subclass for docType couldn't be determined or if the object couldn't be created. This method is invoked by openDocumentWithContentsOfFile.

See Also: makeUntitledDocumentOfType, openDocument



makeDocumentWithContentsOfURL

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

Creates and returns an NSDocument object for document type docType from the contents of anURL. Returns null if the NSDocument subclass for docType couldn't be determined or if the object couldn't be created. This method is invoked by openDocumentWithContentsOfURL.

See Also: makeUntitledDocumentOfType, openDocument



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 subclass used to instantiate the document object.

See Also: openDocument



noteNewRecentDocumentURL

public void noteNewRecentDocumentURL(java.net.URL anURL)

This method should be called by non NSDocument-based apps when they open/save documents. NSDocument automatically calls this method when appropriate for NSDocument-based apps. You can override this in an NSDocument-based application to prevent certain kinds of documents from getting into the list (but you have to identify them by their URL).

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 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 subclass 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 flag)

Returns an NSDocument object created from the contents of anURL and displays it if flag is true. The returned object is added to the receiver's list of managed documents. Returns null if the object could not be created, typically because anURL does not point to a valid location or because there is no NSDocument subclass for the document type. Even if flag is true, the document is not displayed if shouldCreateUI returns false. This method invokes makeDocumentWithContentsOfURL to obtain the created NSDocument object.

See Also: openDocument, openUntitledDocumentOfType, setShouldCreateUI



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 added to the receiver's list of managed documents. Returns null if the object could not be created, typically because no NSDocument subclass 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



recentDocumentURLs

public NSArray recentDocumentURLs()

Returns the list of recent document URLs. This is not a good method to override since the internals of NSDocumentController do not generally use it.

removeDocument

public void removeDocument(NSDocument document)

Removes document from the list of open documents. A document will automatically call removeDocument when it closes. This method is mostly provided for subclassers that want to know when documents close.

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



URLsFromRunningOpenPanel

public NSArray URLsFromRunningOpenPanel()

Description forthcoming.

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.


Table of Contents