---

NSWindowController

Overview

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

• Loading and displaying the window

• Closing the window when appropriate

• Customizing the window’s title

• Storing the window’s frame (size and location) in the defaults database

• Cascading the window in relation to other document windows of the application

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.

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.

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:

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

Tasks

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

Instance Methods

close

Closes the window if it was loaded.

public void close()

Discussion

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” for an overview of deallocation behavior when a window is closed.

See Also

• shouldCloseDocument
• setShouldCloseDocument

document

Returns the NSDocument object associated with the receiver or null if there is none.

public NSDocument document()

Discussion

When a window controller is added to an NSDocument’s list of window controllers, the document sets the window controller’s document with setDocument. The Application Kit uses this outlet to access the document for relevant next-responder messages.

See Also

• setDocument

isWindowLoaded

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

public boolean isWindowLoaded()

See Also

• loadWindow
• window
• windowDidLoad
• windowWillLoad

loadWindow

Loads the receiver’s window from the nib file.

public void loadWindow()

Discussion

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

Returns the owner of the nib file containing the window managed by the receiver.

public Object owner()

Discussion

This owner is usually this, but can be the receiver’s document (an instance of an NSDocument subclass) or some other object.

See Also

• windowNibName

setDocument

Sets the document associated with the window managed by the receiver.

public void setDocument(NSDocument document)

Discussion

document is an instance of an NSDocument subclass that represents and manages the data displayed and captured in the window. Documents automatically call this method when they add a window controller to their list of window controllers; if you are using a subclass of NSDocument, you should not call it directly.

See Also

• document

setDocumentEdited

Sets the document edited flag for the window controller to flag.

public void setDocumentEdited(boolean flag)

Discussion

The window controller uses this flag to control whether its associated window shows up as dirty. You should not call this method directly for window controllers with an associated NSDocument; NSDocument calls this method on its window controllers as needed.

setShouldCascadeWindows

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) to flag.

public void setShouldCascadeWindows(boolean flag)

Discussion

The default is true.

See Also

• shouldCascadeWindows

setShouldCloseDocument

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).

public void setShouldCloseDocument(boolean flag)

Discussion

The default is false.

See Also

• shouldCloseDocument

setWindow

Sets the window controller’s window to aWindow.

public void setWindow(NSWindow aWindow)

Discussion

This method releases the old window and any associated top-level objects in its nib file and assumes ownership of the new window. You should generally create a new window controller for a new window and release the old window controller instead of using this method.

setWindowFrameAutosaveName

Sets the name under which the window’s frame (its size and location on the screen) is saved in the defaults database.

public void setWindowFrameAutosaveName(String name)

Discussion

By default, name is an empty string, causing no information to be stored in the defaults database.

See Also

• windowFrameAutosaveName
• setFrameAutosaveName (NSWindow)

shouldCascadeWindows

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

public boolean shouldCascadeWindows()

Discussion

The default is true.

See Also

• setShouldCascadeWindows

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).

public boolean shouldCloseDocument()

Discussion

The default is false.

See Also

• setShouldCloseDocument

showWindow

This action method displays the window associated with the receiver.

public void showWindow(Object sender)

Discussion

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

Synchronizes the displayed window title and the represented filename with the information in the associated document.

public void synchronizeWindowTitleWithDocumentName()

Discussion

Does nothing if the window controller has no associated document or loaded window. This method queries the window controller’s document to get the document’s display name and full filename path, then calls windowTitleForDocumentDisplayName to get the display name to show in the window title.

window

Returns the window owned by the receiver or null if there isn’t one.

public NSWindow window()

Discussion

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

Allows subclasses of NSWindowController to perform any required tasks after the window owned by the receiver has been loaded.

public void windowDidLoad()

Discussion

The default implementation does nothing.

See Also

• loadWindow
• window
• windowWillLoad

windowFrameAutosaveName

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

public String windowFrameAutosaveName()

See Also

• setWindowFrameAutosaveName

windowNibName

Returns the name of the nib file that stores the window associated with the receiver.

public String windowNibName()

Discussion

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

Returns the full path of the nib file that stores the window associated with the receiver.

public String windowNibPath()

Discussion

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 main bundle 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

Returns displayName by default.

public String windowTitleForDocumentDisplayName(String displayName)

Discussion

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.

See Also

• synchronizeWindowTitleWithDocumentName

windowWillLoad

Allows subclasses of NSWindowController to perform any required tasks before the window owned by the receiver is loaded.

public void windowWillLoad()

Discussion

The default implementation does nothing.

See Also

• loadWindow
• window
• windowDidLoad

---