Mac Developer Library

Developer

AppKit Framework Reference NSWindowController Class Reference

Options
Deployment Target:

On This Page
Language:

NSWindowController

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

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

A window controller 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, a window controller 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 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 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.

  • init(window:) - initWithWindow: Designated Initializer

    Returns a window controller initialized with a given window.

    Declaration

    Swift

    init(window window: NSWindow?)

    Objective-C

    - (instancetype)initWithWindow:(NSWindow *)window

    Parameters

    window

    The window object to manage; can be nil.

    Return Value

    A newly initialized window controller.

    Discussion

    This method is the designated initializer for NSWindowController.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a window controller initialized with a nib file.

    Declaration

    Swift

    convenience init(windowNibName windowNibName: String)

    Objective-C

    - (instancetype)initWithWindowNibName:(NSString *)windowNibName

    Parameters

    windowNibName

    The name of the nib file (minus the “.nib” extension) that archives the receiver’s window; cannot be nil.

    Discussion

    Sets the owner of the nib file to the receiver. The default initialization turns on cascading, sets the shouldCloseDocument flag to NOfalse, and sets the autosave name for the window’s frame to an empty string.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a window controller initialized with a nib file and a specified owner for that nib file.

    Declaration

    Swift

    convenience init(windowNibName windowNibName: String, owner owner: AnyObject)

    Objective-C

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

    Parameters

    windowNibName

    The name of the nib file (minus the “.nib” extension) that archives the receiver’s window; cannot be nil.

    owner

    The nib file's owner; cannot be nil.

    Discussion

    The default initialization turns on cascading, sets the shouldCloseDocument flag to NOfalse, and sets the autosave name for the window’s frame to an empty string.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a window controller initialized with a nib file at an absolute path and a specified owner.

    Declaration

    Swift

    convenience init(windowNibPath windowNibPath: String, owner owner: AnyObject)

    Objective-C

    - (instancetype)initWithWindowNibPath:(NSString *)windowNibPath owner:(id)owner

    Parameters

    windowNibPath

    The full path to the nib file that archives the receiver’s window; cannot be nil.

    owner

    The nib file's owner; cannot be nil.

    Discussion

    Use this method if your nib file is at a fixed location (which is not inside either the file’s owner’s class’s bundle or in the application’s main bundle). The default initialization turns on cascading, sets the shouldCloseDocument flag to NOfalse, and sets the autosave name for the window’s frame to an empty string.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Loads the receiver’s window from the nib file.

    Declaration

    Swift

    func loadWindow()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Displays the window associated with the receiver.

    Declaration

    Swift

    @IBAction func showWindow(_ sender: AnyObject?)

    Objective-C

    - (IBAction)showWindow:(id)sender

    Parameters

    sender

    The control sending the message; can be nil.

    Discussion

    If the window is an NSPanel object and has its becomesKeyOnlyIfNeeded flag set to YEStrue, 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – makeKeyAndOrderFront: (NSWindow)
    – orderFront: (NSWindow)

  • isWindowLoaded - isWindowLoaded Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    - (BOOL)isWindowLoaded

    Return Value

    YEStrue if the nib file containing the receiver’s window has been loaded, NOfalse otherwise.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

  • Returns the window owned by the receiver.

    Declaration

    Swift

    var window: NSWindow?

    Objective-C

    @property(strong) NSWindow *window

    Return Value

    The window owned by the receiver or nil if there isn’t one.

    Discussion

    If the window has not yet been loaded, this method attempts to load the window’s nib file using loadWindow. Before it loads the window, it invokes windowWillLoad, and if the window controller has a document, it invokes the document's corresponding method windowControllerWillLoadNib: (if implemented). After loading the window, this method invokes windowDidLoad and, if there is a document, the NSDocument method windowControllerDidLoadNib: (if implemented).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – windowControllerWillLoadNib: (NSDocument)

  • Sets the window controller’s window.

    Declaration

    Swift

    var window: NSWindow?

    Objective-C

    @property(strong) NSWindow *window

    Parameters

    aWindow

    The new window.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sent after the window owned by the receiver has been loaded.

    Declaration

    Swift

    func windowDidLoad()

    Objective-C

    - (void)windowDidLoad

    Discussion

    The default implementation does nothing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sent before the window owned by the receiver is loaded.

    Declaration

    Swift

    func windowWillLoad()

    Objective-C

    - (void)windowWillLoad

    Discussion

    The default implementation does nothing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    unowned(unsafe) var document: AnyObject?

    Objective-C

    @property(assign) id document

    Parameters

    document

    The new document.

    Discussion

    Documents automatically call this method when they add a window controller to their list of window controllers; you should not call it directly.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – document

  • Returns the document associated with the receiver.

    Declaration

    Swift

    unowned(unsafe) var document: AnyObject?

    Objective-C

    @property(assign) id document

    Return Value

    The document associated with the receiver or nil if there is none.

    Discussion

    When a window controller is added to a document'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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the document edited flag for the window controller.

    Declaration

    Swift

    func setDocumentEdited(_ flag: Bool)

    Objective-C

    - (void)setDocumentEdited:(BOOL)flag

    Parameters

    flag

    YEStrue if the document has been edited since its last save, NOfalse if it hasn't.

    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 document; the document calls this method on its window controllers as needed.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Closes the window if it was loaded.

    Declaration

    Swift

    func close()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns whether the receiver necessarily closes the associated document when the window it manages is closed.

    Declaration

    Swift

    var shouldCloseDocument: Bool

    Objective-C

    @property BOOL shouldCloseDocument

    Return Value

    YEStrue if the receiver necessarily closes the associated document when the window it manages is closed, NOfalse otherwise.

    Discussion

    If NOfalse, the document is closed only when the last remaining window of the document is closed.

    The default is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether the receiver should necessarily close the associated document when the window it manages is closed.

    Declaration

    Swift

    var shouldCloseDocument: Bool

    Objective-C

    @property BOOL shouldCloseDocument

    Parameters

    flag

    YEStrue if the receiver necessarily closes the associated document when the window it manages is closed, NOfalse otherwise.

    Discussion

    If NOfalse, the document is closed only when the last remaining window of the document is closed.

    The default is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    unowned(unsafe) var owner: AnyObject { get }

    Objective-C

    @property(assign, readonly) id owner

    Return Value

    The owner of the nib file containing the window managed by the receiver; usually self, but can be the receiver’s document or some other object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var windowNibName: String? { get }

    Objective-C

    @property(copy, readonly) NSString *windowNibName

    Return Value

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

    Discussion

    If initWithWindowNibPath:owner: was used to initialize the instance, windowNibName returns the last path component with the “.nib” extension stripped off. If initWithWindowNibName: or initWithWindowNibName:owner: was used, windowNibName returns the name without the “.nib” extension.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – owner

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

    Declaration

    Swift

    var windowNibPath: String? { get }

    Objective-C

    @property(copy, readonly) NSString *windowNibPath

    Return Value

    The full path of the nib file that stores the window associated with the receiver; nil if it cannot be located.

    Discussion

    If initWithWindowNibPath:owner: was used to initialize the instance, the path is just returned. If initWithWindowNibName: or initWithWindowNibName:owner: was used, 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 nil if it cannot be located). Subclasses can override this to augment the search behavior, but probably ought to call super first.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether the window should cascade in relation to other document windows.

    Declaration

    Swift

    var shouldCascadeWindows: Bool

    Objective-C

    @property BOOL shouldCascadeWindows

    Parameters

    flag

    YEStrue if the window should cascade in relation to other document windows, NOfalse otherwise.

    Discussion

    Cascading in relation to other document windows means having a slightly offset location so that the title bars of previously displayed windows are still visible.

    The default is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var shouldCascadeWindows: Bool

    Objective-C

    @property BOOL shouldCascadeWindows

    Return Value

    YEStrue if the window will cascade in relation to other document windows, NOfalse otherwise.

    Discussion

    The default is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the name under which the window’s frame is saved in the defaults database.

    Declaration

    Swift

    var windowFrameAutosaveName: String?

    Objective-C

    @property(copy) NSString *windowFrameAutosaveName

    Parameters

    name

    The name under which the window’s frame is saved in the defaults database.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var windowFrameAutosaveName: String?

    Objective-C

    @property(copy) NSString *windowFrameAutosaveName

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func synchronizeWindowTitleWithDocumentName()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the window title to be used for a given document display name.

    Declaration

    Swift

    func windowTitleForDocumentDisplayName(_ displayName: String) -> String

    Objective-C

    - (NSString *)windowTitleForDocumentDisplayName:(NSString *)displayName

    Parameters

    displayName

    The display name for the document. This is the last path component under which the document file is saved.

    Discussion

    The default implementation returns displayName. 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.