- Inherits from:
- NSResponder : NSObject
- Package:
- com.apple.yellow.application
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.
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.
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.
- 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
public NSWindowController()
public NSWindowController(NSWindow window)
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)
.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)
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)
public void close()
See Also: shouldCloseDocument, setShouldCloseDocument
public NSDocument document()
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
public boolean isWindowLoaded()
See Also: loadWindow, window, windowDidLoad, windowWillLoad
public void loadWindow()
See Also: isWindowLoaded
public Object owner()
See Also: windowNibName
public void setDocument(NSDocument document)
See Also: document
public void setDocumentEdited(boolean flag)
public void setShouldCascadeWindows(boolean flag)
true
.See Also: shouldCascadeWindows
public void setShouldCloseDocument(boolean flag)
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
public void setWindow(NSWindow aWindow)
public void setWindowFrameAutosaveName(String name)
See Also: windowFrameAutosaveName, setFrameAutosaveName (NSWindow)
public boolean shouldCascadeWindows()
See Also: setShouldCascadeWindows
public boolean shouldCloseDocument()
true
)
or whether the document is closed only when the last remaining window
of the document is closed (false
).See Also: setShouldCloseDocument
public void showWindow(Object sender)
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)
public void synchronizeWindowTitleWithDocumentName()
public NSWindow window()
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)
public void windowDidLoad()
See Also: loadWindow, window, windowWillLoad
public String windowFrameAutosaveName()
See Also: setWindowFrameAutosaveName
public String windowNibName()
nib
" extension
stripped off. If the nib name was passed, windowNibName returns
the name without the ".nib
"
extension. See Also: owner
public String windowNibPath()
public String windowTitleForDocumentDisplayName(String displayName)
public void windowWillLoad()
See Also: loadWindow, window, windowDidLoad