[Previous] [Class List] [Next]

NSWindowController


Inherits from: NSObject
Conforms to: NSObject
(NSObject)
NSCoding (NSObject)
Declared in: AppKit/NSWindowController.h




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

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

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


Adopted Protocols


NSCoding
- encodeWithCoder:
- initWithCoder:

Method Types


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:


Instance Methods



close

- (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

- (id)document

Returns the NSDocument object associated with the receiver or 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:



initWithWindow:

- (id)initWithWindow:(NSWindow *)window

Returns an NSWindowController object initialized with window, the window object to manage. The window argument can be 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.

initWithWindowNibName:

- (id)initWithWindowNibName:(NSString *)windowNibName

Returns an NSWindowController object initialzed with windowNibName, the name of the nib file (minus the ".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.

initWithWindowNibName:owner:

- (id)initWithWindowNibName:(NSString *)windowNibName owner:(id)owner

Returns an NSWindowController object initialzed with windowNibName and owner. Neither windowNibName or owner can be 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.

isWindowLoaded

- (BOOL)isWindowLoaded

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

See Also: - loadWindow, - window, - windowDidLoad, - windowWillLoad



loadWindow

- (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

- (id)owner

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

See Also: - windowNibName



setDocument:

- (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 document when it is part of a document-based application.

See Also: - document



setShouldCascadeWindows:

- (void)setShouldCascadeWindows:(BOOL)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 YES.

See Also: - shouldCascadeWindows



setShouldCloseDocument:

- (void)setShouldCloseDocument:(BOOL)flag

Sets whether the receiver should close the associated document when the window it manages is closed (flag is 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



setWindowFrameAutosaveName:

- (void)setWindowFrameAutosaveName:(NSString *)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

- (BOOL)shouldCascadeWindows

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

See Also: - setShouldCascadeWindows:



shouldCloseDocument

- (BOOL)shouldCloseDocument

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

See Also: - setShouldCloseDocument:



showWindow:

- (void)showWindow:(id)sender

Displays the window associated with the receiver. If the window is an NSPanel object and has its becomesKeyOnlyIfNeeded flag set to 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)



window

- (NSWindow *)window

Returns the window owned by the receiver or 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)



windowDidLoad

- (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

- (NSString *)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

- (NSString *)windowNibName

Returns the name of the nib file that stores the window associated with the receiver. The name does not include the ".nib" extension.

See Also: - owner



windowTitleForDocumentDisplayName:

- (NSString *)windowTitleForDocumentDisplayName:(NSString *)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

- (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




[Previous] [Next]