- Inherits from:
- NSObject
- Conforms to:
- NSCoding
- NSObject (NSObject)
Declared in:
- AppKit/NSWindowController.h
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: methodand in your implementations include the following line of code:
[self autorelease];
As a consequence of autoreleasing itself, a NSWindowController object autoreleases its window as well as all other top-level objects in its nib file. 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 either one of the initWithWindowNibName:... initializers or the initWithWindow: initializer. 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.
NSCoding
- - encodeWithCoder:
- - initWithCoder:
- Initializing NSWindowControllers
- - initWithWindow:
- - initWithWindowNibName:
- - initWithWindowNibName:owner:
- - initWithWindowNibPath:owner:
- 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:
- (void)close
See Also: - shouldCloseDocument, - setShouldCloseDocument:
- (id)document
nil
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:
- (id)initWithWindow:(NSWindow
*)window
nil
.This initializer is useful
when a window has been loaded but no window controller is assigned.
This is the designated initializer for NSWindowController. The default initialization
turns on cascading, sets the shouldCloseDocument flag to NO
,
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 NSWindowWillCloseNotifications 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.- (id)initWithWindowNibName:(NSString
*)windowNibName
.nib
"
extension) that archives the receiver's window. The windowNibName argument cannot
be nil
. Sets the owner of the nib
file to the receiver. The default initialization turns on cascading,
sets the shouldCloseDocument flag
to NO
, and sets the autosave name
for the window's frame to an empty string.- (id)initWithWindowNibName:(NSString
*)windowNibName
owner:(id)owner
nil
. 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 NO
, and sets the autosave name
for the window's frame to an empty string.- (id)initWithWindowNibPath:(NSString
*)windowNibPath
owner:(id)owner
- (BOOL)isWindowLoaded
See Also: - loadWindow, - window, - windowDidLoad, - windowWillLoad
- (void)loadWindow
See Also: - isWindowLoaded
- (id)owner
See Also: - windowNibName
- (void)setDocument:(NSDocument
*)document
See Also: - document
- (void)setDocumentEdited:(BOOL)flag
- (void)setShouldCascadeWindows:(BOOL)flag
YES
.See Also: - shouldCascadeWindows
- (void)setShouldCloseDocument:(BOOL)flag
YES
)
or whether to close the document only when the last document window
has been closed (flag is NO
). The
default is NO
. See Also: - shouldCloseDocument
- (void)setWindow:(NSWindow
*)aWindow
- (void)setWindowFrameAutosaveName:(NSString
*)name
See Also: - windowFrameAutosaveName, - setFrameAutosaveName: (NSWindow)
- (BOOL)shouldCascadeWindows
See Also: - setShouldCascadeWindows:
- (BOOL)shouldCloseDocument
YES
)
or whether the document is closed only when the last remaining window
of the document is closed (NO
).See Also: - setShouldCloseDocument:
- (void)showWindow:(id)sender
YES
, 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)
- (void)synchronizeWindowTitleWithDocumentName
- (NSWindow *)window
nil
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)
- (void)windowDidLoad
See Also: - loadWindow, - window, - windowWillLoad
- (NSString *)windowFrameAutosaveName
See Also: - setWindowFrameAutosaveName:
- (NSString *)windowNibName
nib
"
extension stripped off. If initWithWindowNibName: or initWithWindowNibName:owner: were
used, windowNibName returns the name without
the ".nib
" extension. See Also: - owner
- (NSString *)windowNibPath
- (NSString *)windowTitleForDocumentDisplayName:(NSString
*)displayName
- (void)windowWillLoad
See Also: - loadWindow, - window, - windowDidLoad