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

Table of Contents

NSWindowController


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


Class Description


An NSWindowController object manages a window, usually a window stored in a nib file. This management entails:

An NSWindowController can manage a window by itself or as a role player in the Application Kit's document-based architecture, which also includes NSDocument and NSDocumentController objects. In this architecture, an NSWindowController is created and managed by a "document" (an instance of an NSDocument subclass) and, in turn, keeps a reference to the document. For a discussion of this architecture, see "Document-Based Application Architecture" in the NSDocument specification.

The relationship between an NSWindowController (or, simply, a window controller) and a nib file is important. Although a window controller can manage a programmatically created window, it usually manages a window in a nib file. The nib file can contain other top-level objects, including other windows, but the window controller's responsibility is this primary window. The window controller is usually the owner of the nib file, even when it is part of a document-based application. Regardless of who is the file's owner, the window controller is responsible for freeing all top-level objects in the nib file it loads.

For simple documents-that is, documents with only one nib file containing a window-you need do little directly with NSWindowController. The Application Kit will create one for you. However, if the default window controller is not sufficient, you can create a custom subclass of NSWindowController. For documents with multiple windows or panels, your document must create separate instances of NSWindowController (or of custom subclasses of NSWindowController), one for each window or panel. An example is a CAD application that has different windows for side, top, and front views of drawn objects. What you do in your NSDocument subclass determines whether the default NSWindowController or separately created and configured NSWindowController objects are used.


Window Closing Behavior


When a window is closed and it is part of a document-based application, the document removes the window's NSWindowController from its list of window controllers. This results in the deallocation of the window controller and the window, and possibly the deallocation of the NSDocument object itself. But when a window controller is not part of a document-based application, closing the window by default does not result in the deallocation of the window or window controller. This is desired behavior for a window controller that manages something like an Inspector panel; you shouldn't have to load the nib file again and recreate the objects the next time the user requests the Inspector.

If you want the closing of a window to make both window and window controller go away when it isn't part of a document, your subclass of NSWindowController can observe NSWindow's NSWindowWillCloseNotification or, as window delegate, implement the windowWillClose method.

In any case, a window controller should not get rid of its window until it ensures its own deallocation.


Subclassing NSWindowController


You should create a subclass of NSWindowController when you want to augment the default behavior, such as to give the window a custom title or to perform some setup tasks before the window is loaded. In your class's initialization method, be sure to invoke on super one of the constructors. Which one depends on whether the window object originates in a nib file or is programmatically created.

Three NSWindowController methods are most commonly overridden:


Method Name Description
windowWillLoad Override to perform tasks before the window nib file is loaded.
windowDidLoad Override to perform tasks after the window nib file is loaded.
windowTitleForDocumentDisplayName Override to customize the window title.

You can also override loadWindow to get different nib-searching or nib-loading behavior, although there is usually no need to do this.




Method Types


Constructors
NSWindowController
Loading and display the window
loadWindow
showWindow
isWindowLoaded
window
setWindow
windowDidLoad
windowWillLoad
Setting and getting the document
setDocument
document
setDocumentEdited
Closing the window
close
shouldCloseDocument
setShouldCloseDocument
Getting nib file information
owner
windowNibName
windowNibPath
Setting and getting window attributes
setShouldCascadeWindows
shouldCascadeWindows
setWindowFrameAutosaveName
synchronizeWindowTitleWithDocumentName
windowFrameAutosaveName
windowTitleForDocumentDisplayName


Constructors



NSWindowController

public NSWindowController()

Description forthcoming.

public NSWindowController(NSWindow window)

Returns an NSWindowController object initialized with window, the window object to manage.The window argument can be null.This initializer is useful when a window has been loaded but no window controller is assigned. The default initialization turns on cascading, sets the shouldCloseDocument flag to false, and sets the window frame autosave name to an empty string. As a side effect, the created window controller is added as an observer of the WindowWillCloseNotifications posted by that window object (which is handled by a private method). If you make the window controller a delegate of the window, you can implement NSWindow's windowShouldClose delegate method.

public NSWindowController(String windowNibName)

Returns an NSWindowController object initialized with windowNibName, the name of the nib file (minus the ".nib" extension) that archives the receiver's window. The windowNibName argument cannot be null. Sets the owner of the nib file to the receiver. The default initialization turns on cascading, sets the shouldCloseDocument flag to false, and sets the autosave name for the window's frame to an empty string.

public NSWindowController( String windowNibName, Object owner)

Returns an NSWindowController object initialized with windowNibName and owner. Neither windowNibName or owner can be null. The windowNibName argument is the name of the nib file (minus the ".nib" extension) that archives the receiver's window. The owner argument is the nib file's owner. The default initialization turns on cascading, sets the shouldCloseDocument flag to false, and sets the autosave name for the window's frame to an empty string.

public NSWindowController( String windowNibName, Object owner, boolean flag)

Description forthcoming.


Instance Methods



close

public void close()

Closes the window if it was loaded. Because this method closes the window without asking the user for confirmation, you usually do not invoke it when the Close menu command is chosen. Instead invoke NSWindow's performClose on the receiver's window. See "Window Closing Behavior" in the class description for an overview of deallocation behavior when a window is closed.

See Also: shouldCloseDocument, setShouldCloseDocument



document

public NSDocument document()

Returns the NSDocument object associated with the receiver or null if there is none. If the receiver is part of a document-based application, it typically keeps a reference to its NSDocument. When a window is loaded or the document changes, the NSWindowController gets the edited status from the document and sets the window with it (NSWindow's setDocumentEdited). The Application Kit also uses this outlet to access the document for relevant next-responder messages.

See Also: setDocument



isWindowLoaded

public boolean isWindowLoaded()

Returns whether the nib file containing the receiver's window has been loaded.

See Also: loadWindow, window, windowDidLoad, windowWillLoad



loadWindow

public void loadWindow()

Loads the receiver's window from the nib file. You should never directly invoke this method. Instead, invoke window so the windowDidLoad and windowWillLoad methods are invoked. Subclasses can override this method if the way it finds and loads the window is not adequate. It uses NSBundle's bundleForClass method to get the bundle, using the class of the nib file owner as argument. It then locates the nib file within the bundle and, if successful, loads it; if unsuccessful, it tries to find the nib file in the main bundle.

See Also: isWindowLoaded



owner

public Object owner()

Returns the owner of the nib file containing the window managed by the receiver. This is usually this, but can be the receiver's document (an instance of an NSDocument subclass) or some other object.

See Also: windowNibName



setDocument

public void setDocument(NSDocument document)

Sets the document associated with the window managed by the receiver. A document is an instance of an NSDocument subclass that represents and manages the data displayed and captured in the window. A window controller has a reference to its document when it is part of a document-based application.

See Also: document



setDocumentEdited

public void setDocumentEdited(boolean flag)

Description forthcoming.

setShouldCascadeWindows

public void setShouldCascadeWindows(boolean flag)

Sets whether the window, when it is displayed, should cascade in relation to other document windows (that is, have a slightly offset location so that the title bars of previously displayed windows are still visible). The default is true.

See Also: shouldCascadeWindows



setShouldCloseDocument

public void setShouldCloseDocument(boolean flag)

Sets whether the receiver should close the associated document when the window it manages is closed (flag is true) or whether to close the document only when the last document window has been closed (flag is false). The default is false.

See Also: shouldCloseDocument



setWindow

public void setWindow(NSWindow aWindow)

Description forthcoming.

setWindowFrameAutosaveName

public void setWindowFrameAutosaveName(String name)

Sets the name under which the window's frame (it's size and location on the screen) is saved in the defaults database. By default, name is an empty string, causing no information to be stored in the defaults database.

See Also: windowFrameAutosaveName, setFrameAutosaveName (NSWindow)



shouldCascadeWindows

public boolean shouldCascadeWindows()

Returns whether the window will cascade in relation to other document windows when it is displayed.

See Also: setShouldCascadeWindows



shouldCloseDocument

public boolean shouldCloseDocument()

Returns whether the receiver closes the associated document when the window it manages is closed (true) or whether the document is closed only when the last remaining window of the document is closed (false).

See Also: setShouldCloseDocument



showWindow

public void showWindow(Object sender)

Displays the window associated with the receiver. If the window is an NSPanel object and has its becomesKeyOnlyIfNeeded flag set to true, the window is displayed in front of all other windows but is not made key; otherwise it is displayed in front and is made key. This method is useful for menu actions.

See Also: makeKeyAndOrderFront (NSWindow), orderFront (NSWindow)



synchronizeWindowTitleWithDocumentName

public void synchronizeWindowTitleWithDocumentName()

Description forthcoming.

window

public NSWindow window()

Returns the window owned by the receiver or null if there isn't one. If the window has not yet been loaded, it attempts to load the window's nib file using loadWindow. Before it loads the window, it invokes windowWillLoad in subclass implementations and, if the NSWindowController has a document, it invokes the NSDocument's corresponding method windowControllerWillLoadNib (if implemented). After loading the window, it invokes windowDidLoad and, if there is a document, the NSDocument method windowControllerDidLoadNib (if implemented).

See Also: windowControllerWillLoadNib (NSDocument)



windowDidLoad

public void windowDidLoad()

Allows subclasses of NSWindowController to perform any required tasks after the window owned by the receiver has been loaded. The default implementation does nothing.

See Also: loadWindow, window, windowWillLoad



windowFrameAutosaveName

public String windowFrameAutosaveName()

Returns the name under which the frame rectangle of the window owned by the receiver is stored in the defaults database.

See Also: setWindowFrameAutosaveName



windowNibName

public String windowNibName()

Returns the name of the nib file that stores the window associated with the receiver. If the nib path was passed to the constructor, windowNibName returns the last path component with the ".nib" extension stripped off. If the nib name was passed, windowNibName returns the name without the ".nib" extension.

See Also: owner



windowNibPath

public String windowNibPath()

Returns the full path of the nib file that stores the window associated with the receiver. If the nib path was passed to the constructor, the path is just returned. If the nib name was passed, windowNibPath locates the nib in the file's owner's class' bundle or in the application's mainBundle and returns the full path (or null if it cannot be located). Subclasses can override this to augment the search behavior, but probably ought to call super first.

windowTitleForDocumentDisplayName

public String windowTitleForDocumentDisplayName(String displayName)

Returns displayName by default. The display name, which is generally maintained by the associated NSDocument, is the last path component under which the document file is saved. Subclasses can override this method to customize the window title. For example, a CAD application could append "-Top" or "-Side", depending on the view displayed by the window.

windowWillLoad

public void windowWillLoad()

Allows subclasses of NSWindowController to perform any required tasks before the window owned by the receiver is loaded. The default implementation does nothing.

See Also: loadWindow, window, windowDidLoad




Table of Contents