Inherits from: NSObject
Conforms to: NSObject
(NSObject)
NSCoding (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 architeture, 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 overriden:
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:
- Loading and display the window
- - loadWindow
- - showWindow:
- - isWindowLoaded
- - window
- - windowDidLoad
- - windowWillLoad
- Setting and getting the document
- - setDocument:
- - document
- Closing the window - close
- - shouldCloseDocument
- - setShouldCloseDocument:
- Getting nib file information
- - owner
- - windowNibName
- Setting and getting window attributes
- - setShouldCascadeWindows:
- - shouldCascadeWindows
- - setWindowFrameAutosaveName:
- - 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
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. - (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)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)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)
- (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
See Also: - owner
- (NSString *)windowTitleForDocumentDisplayName:(NSString *)displayName
- (void)windowWillLoad
See Also: - loadWindow, - window, - windowDidLoad