NSWindow Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSDrawer.h
NSGraphics.h
NSLayoutConstraint.h
NSWindow.h
NSWindowRestoration.h
Related sample code

Overview

The NSWindow class defines objects (known as windows) that manage and coordinate the windows an application displays on the screen. A single NSWindow object corresponds to at most one onscreen window. The two principal functions of a window are to provide an area in which views can be placed and to accept and distribute, to the appropriate views, events the user instigates through actions with the mouse and keyboard.

Tasks

Creating Windows

Configuring Windows

Accessing Window Information

Getting Layout Information

Managing Windows

Managing Sheets

Sizing Windows

Sizing Content

Managing Window Layers

Managing Window Visibility and Occlusion State

Managing Window Frames in User Defaults

Managing Key Status

Managing Main Status

Managing Toolbars

Managing Attached Windows

Managing Window Buffers

Managing Default Buttons

Managing Field Editors

Managing the Window Menu

Managing Cursor Rectangles

Managing Title Bars

Managing Tooltips

Handling Events

Managing Responders

Managing the Key View Loop

Handling Keyboard Events

Handling Mouse Events

Handling Window Restoration

Bracketing Drawing Operations

Drawing Windows

Window Animation

Updating Windows

Dragging Items

Converting Coordinates

Accessing Edited Status

Managing Titles

Accessing Screen Information

Moving Windows

Closing Windows

Minimizing Windows

Getting the Dock Tile

Printing Windows

Providing Services

Working with Carbon

Triggering Constraint-Based Layout

Debugging Constraint-Based Layout

See Cocoa Auto Layout Release Notes for more details on debugging constraint-based layout.

Constraint-Based Layouts

Class Methods

contentRectForFrameRect:styleMask:

Returns the content rectangle used by a window with a given frame rectangle and window style.

+ (NSRect)contentRectForFrameRect:(NSRect)windowFrame styleMask:(NSUInteger)windowStyle
Parameters
windowFrame

The frame rectangle for the window expressed in screen coordinates.

windowStyle

The window style for the window. See “Constants” for a list of style mask values.

Return Value

The content rectangle, expressed in screen coordinates, used by the window with windowFrame and windowStyle.

Discussion

When a NSWindow instance is available, you should use contentRectForFrameRect: instead of this method.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

defaultDepthLimit

Returns the default depth limit for instances of NSWindow.

+ (NSWindowDepth)defaultDepthLimit
Return Value

The default depth limit for instances of NSWindow, determined by the depth of the deepest screen level available to the window server.

Discussion

The value returned can be examined with the Application Kit functions NSPlanarFromDepth, NSColorSpaceFromDepth, NSBitsPerSampleFromDepth, and NSBitsPerPixelFromDepth.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

frameRectForContentRect:styleMask:

Returns the frame rectangle used by a window with a given content rectangle and window style.

+ (NSRect)frameRectForContentRect:(NSRect)windowContentRect styleMask:(NSUInteger)windowStyle
Parameters
windowContentRect

The content rectangle for a window expressed in screen coordinates.

windowStyle

The window style for the window. See “Window Style Masks” for a list of style mask values.

Return Value

The frame rectangle, expressed in screen coordinates, used by the window with windowContentRect and windowStyle.

Discussion

When a NSWindow instance is available, you should use frameRectForContentRect: instead of this method.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

menuChanged:

This method does nothing; it is here for backward compatibility.

+ (void)menuChanged:(NSMenu *)menu
Parameters
menu

The menu object that changed.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

minFrameWidthWithTitle:styleMask:

Returns the minimum width a window’s frame rectangle must have for it to display a title, with a given window style.

+ (CGFloat)minFrameWidthWithTitle:(NSString *)windowTitle styleMask:(NSUInteger)windowStyle
Parameters
windowTitle

The title for the window.

windowStyle

The window style for the window. See “Window Style Masks” for a list of style mask values.

Return Value

The minimum width of the window’s frame, using windowStyle, in order to display windowTitle.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

removeFrameUsingName:

Removes the frame data stored under a given name from the application’s user defaults.

+ (void)removeFrameUsingName:(NSString *)frameName
Parameters
frameName

The name of the frame to remove.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

standardWindowButton:forStyleMask:

Returns a new instance of a given standard window button, sized appropriately for a given window style.

+ (NSButton *)standardWindowButton:(NSWindowButton)windowButtonKind forStyleMask:(NSUInteger)windowStyle
Parameters
windowButtonKind

The kind of standard window button to return.

windowStyle

The window style for which windowButtonKind is to be sized. See “Window Style Masks” for the list of allowable values.

Return Value

The new window button of the kind identified by windowButtonKind; nil when no such button kind exists.

Discussion

The caller is responsible for adding the button to the view hierarchy and for setting the target to be the window.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSWindow.h

windowNumberAtPoint:belowWindowWithWindowNumber:

Returns the number of the frontmost window that would be hit by a mouse-down at the specified screen location.

+ (NSInteger)windowNumberAtPoint:(NSPoint)point belowWindowWithWindowNumber:(NSInteger)windowNumber
Parameters
point

The location of the mouse-down in screen coordinates.

windowNumber

If non-0, the search will start below windowNumber window in z-order.

Return Value

The window number of the window under the point. The window number returned may correspond to a window in another application.

Discussion

Because this method uses the same rules as mouse-down hit-testing, windows with transparency at the given point, and windows that ignore mouse events, will not be returned.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

windowNumbersWithOptions:

Returns the window numbers for all visible windows satisfying the specified options.

+ (NSArray *)windowNumbersWithOptions:(NSWindowNumberListOptions)options
Parameters
options

The possible options are specified in “NSWindowNumberListOptions”.

Return Value

An array of window numbers for all visible windows satisfying the specified options. (Windows on the active space are returned in z-order; that is, front to back.)

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

Instance Methods

acceptsMouseMovedEvents

Indicates whether the window accepts mouse-moved events.

- (BOOL)acceptsMouseMovedEvents
Return Value

YES when the window accepts (and distributes) mouse-moved events; otherwise, NO.

Discussion

The NSWindow default is NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

addChildWindow:ordered:

Adds a given window as a child window of the window.

- (void)addChildWindow:(NSWindow *)childWindow ordered:(NSWindowOrderingMode)orderingMode
Parameters
childWindow

The child window to order.

orderingMode
  • NSWindowAbove: childWindow is ordered immediately in front of the window.

  • NSWindowBelow: childWindow is ordered immediately behind the window.

Discussion

After the childWindow is added as a child of the window, it is maintained in relative position indicated by orderingMode for subsequent ordering operations involving either window. While this attachment is active, moving childWindow will not cause the window to move (as in sliding a drawer in or out), but moving the window will cause childWindow to move.

Note that you should not create cycles between parent and child windows. For example, you should not add window B as child of window A, then add window A as a child of window B.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSWindow.h

allowsConcurrentViewDrawing

Indicates whether the window allows multithreaded view drawing.

- (BOOL)allowsConcurrentViewDrawing
Return Value

YES if the window allows multithreaded view drawing; otherwise, NO.

Discussion

The default value is YES.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

allowsToolTipsWhenApplicationIsInactive

Indicates whether the window can display tooltips even when the application is in the background.

- (BOOL)allowsToolTipsWhenApplicationIsInactive
Return Value

YES if the window can display tooltips even when the application is in the background; otherwise, NO.

Discussion

The default is NO.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

alphaValue

Returns the window’s alpha value.

- (CGFloat)alphaValue
Return Value

The window’s alpha value.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

anchorAttributeForOrientation:

Returns which part of the window stays stationary during constraint based layout.

- (NSLayoutAttribute)anchorAttributeForOrientation:(NSLayoutConstraintOrientation)orientation
Parameters
orientation

The attribute for orientation. The possible values are specified in NSLayoutConstraintOrientation.

Return Value

Returns the layout attribute.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

animationBehavior

Returns the window’s automatic animation behavior.

- (NSWindowAnimationBehavior)animationBehavior
Return Value

The window’s animation behavior. See “NSWindowAnimationBehavior” for the possible values.

Discussion

This controls the automatic window animation behavior used when a window is sent an orderFront: or orderOut: message. See setAnimationBehavior: for more information.

By default, a window’s animation behavior is set to NSWindowAnimationBehaviorDefault, which causes AppKit to determine the style of animation to use automatically based on its inference of a window’s “type” from various window properties.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindow.h

animationResizeTime:

Specifies the duration of a smooth frame-size change.

- (NSTimeInterval)animationResizeTime:(NSRect)newWindowFrame
Parameters
newWindowFrame

The frame rectangle specified in setFrame:display:animate:.

Return Value

The duration of the frame size change.

Discussion

Subclasses can override this method to control the total time for the frame change.

The NSWindow implementation uses the value from the NSWindowResizeTime user default as the time in seconds to resize by 150 pixels. If this value is unspecified, NSWindowResizeTime is 0.20 seconds (this default value may be different in different releases of OS X).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

areCursorRectsEnabled

Indicates whether the window’s cursor rectangles are enabled.

- (BOOL)areCursorRectsEnabled
Return Value

YES when cursor rectangles are enabled; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

aspectRatio

Returns the window’s aspect ratio, which constrains the size of its frame rectangle to integral multiples of this ratio when the user resizes it.

- (NSSize)aspectRatio
Return Value

The window’s aspect ratio.

Discussion

The size of the window’s frame rectangle is constrained to integral multiples of this ratio when the user resizes it. You can set an NSWindow object’s size to any ratio programmatically.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

attachedSheet

Returns the sheet attached to the window.

- (NSWindow *)attachedSheet
Return Value

The sheet attached to the window; nil when the window doesn’t have a sheet attached.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSWindow.h

autorecalculatesContentBorderThicknessForEdge:

Indicates whether the window calculates the thickness of a given border automatically.

- (BOOL)autorecalculatesContentBorderThicknessForEdge:(NSRectEdge)edge
Parameters
edge

The border to check:

Return Value

YES when the window auto-recalculates the given border’s thickness; otherwise, NO.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

autorecalculatesKeyViewLoop

Indicates whether the window automatically recalculates the key view loop when views are added.

- (BOOL)autorecalculatesKeyViewLoop
Return Value

YES if the window automatically recalculates the key view loop when views are added; otherwise, NO.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSWindow.h

backgroundColor

Returns the color of the window’s background.

- (NSColor *)backgroundColor
Return Value

The window’s background color.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

backingAlignedRect:options:

Returns a backing store pixel aligned rectangle in window coordinates.

- (NSRect)backingAlignedRect:(NSRect)aRect options:(NSAlignmentOptions)options
Parameters
aRect

The rectangle in view coordinates.

options

The alignment options. See NSAlignmentOptions for possible values.

Return Value

A rectangle that is aligned to the backing store pixels using the specified options. The rectangle is in window coordinates.

Discussion

Uses the NSIntegralRectWithOptions function to produce a backing store pixel aligned rectangle from the given input rectangle in window coordinates.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindow.h

backingLocation

Indicates the window’s backing store location.

- (NSWindowBackingLocation)backingLocation
Return Value

The location of the window’s backing store. See “NSWindowBackingLocation” for possible values.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

backingScaleFactor

Returns the backing scale factor.

- (CGFloat)backingScaleFactor
Return Value

Returns 2.0 for high-resolution scaled display modes, and 1.0 for all other cases.

Discussion

There are some scenarios where an application that is resolution-aware may want to reason on its own about the display environment it is running in.

It is important to note that this number returned by this method does not represent anything concrete, such as pixel density or physical size, since it can vary based on the configured display mode. For example, the display may be in a mirrored configuration that is still high-resolution scaled, resulting in pixel geometry that may not match the native resolution of the display device.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindow.h

backingType

Returns the window’s backing store type.

- (NSBackingStoreType)backingType
Return Value

The backing store type.

Discussion

The possible return values are described in “NSBackingStoreType—Buffered Window Drawing.”

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

becomeKeyWindow

Invoked automatically to inform the window that it has become the key window; never invoke this method directly.

- (void)becomeKeyWindow
Discussion

This method reestablishes the window’s first responder, sends the becomeKeyWindow message to that object if it responds, and posts an NSWindowDidBecomeKeyNotification to the default notification center.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

becomeMainWindow

Invoked automatically to inform the window that it has become the main window; never invoke this method directly.

- (void)becomeMainWindow
Discussion

This method posts an NSWindowDidBecomeMainNotification to the default notification center.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

beginCriticalSheet:completionHandler:

Starts a document-modal session and presents the specified critical sheet.

- (void)beginCriticalSheet:(NSWindow *)sheetWindow completionHandler:(void (^)(NSModalResponse returnCode))handler
Parameters
sheetWindow

The window object that represents the critical sheet to present. A critical sheet contains content that is time-critical or very important to the user.

handler

The completion handler that gets called when the sheet’s modal session ends.

Discussion

This method displays the sheet—on top of the window’s current sheet, if one exists—makes it key and returns control to the caller. While the sheet remains visible, most events targeted at the receiver are prohibited. The runloop does not enter any special mode to accomplish this.

If the window already has a sheet when this method runs, the existing sheet is temporarily disabled while the critical sheet is presented. When the critical sheet is dismissed, the previously presented sheet continues its standard operation.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSWindow.h

beginSheet:completionHandler:

Starts a document-modal session and presents—or queues for presentation—a sheet.

- (void)beginSheet:(NSWindow *)sheetWindow completionHandler:(void (^)(NSModalResponse returnCode))handler
Parameters
sheetWindow

The window object that represents the sheet to present.

handler

The completion handler that gets called when the sheet’s modal session ends.

Discussion

If the window already has a presented sheet, this method queues the specified sheet for presentation after the current sheet is dismissed and then returns control to the caller.

If the window has no presented sheets, this method displays the specified sheet, makes it key, and returns control to the caller. While the sheet remains visible, most events targeted at the receiver are prohibited. The runloop does not enter any special mode to accomplish this.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSWindow.h

cacheImageInRect:

Stores the window’s raster image from a given rectangle expressed in the window’s base coordinate system.

- (void)cacheImageInRect:(NSRect)rectangle
Parameters
rectangle

The rectangle representing the image to cache.

Discussion

This method allows the window to perform temporary drawing, such as a band around the selection as the user drags the mouse, and to quickly restore the previous image by invoking restoreCachedImage and flushWindowIfNeeded. The next time the window displays, it discards its cached image rectangles. You can also explicitly use discardCachedImage to free the memory occupied by cached image rectangles. aRect is made integral before caching the image to avoid antialiasing artifacts.

Only the last cached rectangle is remembered and can be restored.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

canBecomeKeyWindow

Indicates whether the window can become the key window.

- (BOOL)canBecomeKeyWindow
Return Value

YES if the window can become the key window, otherwise, NO.

Discussion

Attempts to make the window the key window are abandoned if this method returns NO. The NSWindow implementation returns YES if the window has a title bar or a resize bar, or NO otherwise.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

canBecomeMainWindow

Indicates whether the window can become the application’s main window.

- (BOOL)canBecomeMainWindow
Return Value

YES when the window can become the main window; otherwise, NO.

Discussion

Attempts to make the window the main window are abandoned if this method returns NO. The NSWindow implementation returns YES if the window is visible, is not an NSPanel object, and has a title bar or a resize mechanism. Otherwise it returns NO.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

canBecomeVisibleWithoutLogin

Indicates whether the window can be displayed at the login window. Default: NO.

- (BOOL)canBecomeVisibleWithoutLogin
Return Value

YES when the window can be displayed at the login window; otherwise, NO.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

canHide

Indicates whether the window can be hidden when its application becomes hidden (during execution of the NSApplication hide: method).

- (BOOL)canHide
Return Value

YES if the window can be hidden when its application becomes hidden; otherwise, NO.

Discussion

The default is YES.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

canStoreColor

Indicates whether the window has a depth limit that allows it to store color values.

- (BOOL)canStoreColor
Return Value

YES when the window’s depth limit allows it to store color values; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

cascadeTopLeftFromPoint:

Positions the window's top left to a given point.

- (NSPoint)cascadeTopLeftFromPoint:(NSPoint)topLeft
Parameters
topLeft

The new top-left point, in screen coordinates, for the window. When NSZeroPoint, the window is not moved, except as needed to constrain to the visible screen

Return Value

The point shifted from top left of the window in screen coordinates.

Discussion

The returned point can be passed to a subsequent invocation of cascadeTopLeftFromPoint: to position the next window so the title bars of both windows are fully visible.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

center

Sets the window’s location to the center of the screen.

- (void)center
Discussion

The window is placed exactly in the center horizontally and somewhat above center vertically. Such a placement carries a certain visual immediacy and importance. This method doesn’t put the window onscreen, however; use makeKeyAndOrderFront: to do that.

You typically use this method to place a window—most likely an alert dialog—where the user can’t miss it. This method is invoked automatically when a panel is placed on the screen by the runModalForWindow: method of the NSApplication class.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

childWindows

Returns an array of the window’s attached child windows.

- (NSArray *)childWindows
Return Value

An array containing the window’s child windows.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSWindow.h

close

Removes the window from the screen.

- (void)close
Discussion

If the window is set to be released when closed, a release message is sent to the object after the current event is completed. For an NSWindow object, the default is to be released on closing, while for an NSPanel object, the default is not to be released. You can use the setReleasedWhenClosed: method to change the default behavior.

A window doesn’t have to be visible to receive the close message. For example, when the application terminates, it sends the close message to all windows in its window list, even those that are not currently visible.

The close method posts an NSWindowWillCloseNotification notification to the default notification center.

The close method differs in two important ways from the performClose: method:

  • It does not attempt to send a windowShouldClose: message to the window or its delegate.

  • It does not simulate the user clicking the close button by momentarily highlighting the button.

Use performClose: if you need these features.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

collectionBehavior

Identifies the window’s behavior in window collections.

- (NSWindowCollectionBehavior)collectionBehavior
Return Value

The collection behavior identifier.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

colorSpace

Returns the window’s color space.

- (NSColorSpace *)colorSpace
Return Value

The color space. Will return nil If the window does not have a backing store, and is off-screen.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

constrainFrameRect:toScreen:

Modifies and returns a frame rectangle so that its top edge lies on a specific screen.

- (NSRect)constrainFrameRect:(NSRect)frameRect toScreen:(NSScreen *)screen
Parameters
frameRect

The proposed frame rectangle to adjust.

screen

The screen on which the top edge of the window’s frame is to lie.

Return Value

The adjusted frame rectangle.

Discussion

If the window is resizable and the window’s height is greater than the screen height, the rectangle’s height is adjusted to fit within the screen as well. The rectangle’s width and horizontal location are unaffected. You shouldn’t need to invoke this method yourself; it’s invoked automatically (and the modified frame is used to locate and set the size of the window) whenever a titled NSWindow object is placed onscreen and whenever its size is changed.

Subclasses can override this method to prevent their instances from being constrained or to constrain them differently.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

contentAspectRatio

Returns the window’s content aspect ratio.

- (NSSize)contentAspectRatio
Return Value

The window’s content aspect ratio.

Discussion

The default content aspect ratio is (0, 0).

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

contentBorderThicknessForEdge:

Indicates the thickness of a given border of the window.

- (CGFloat)contentBorderThicknessForEdge:(NSRectEdge)edge
Parameters
edge

The border whose thickness to get:

Return Value

Thickness of the given border, in points.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

contentMaxSize

Returns the maximum size of the window’s content view.

- (NSSize)contentMaxSize
Return Value

The maximum size of the window’s content view.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

contentMinSize

Returns the minimum size of the window’s content view.

- (NSSize)contentMinSize
Return Value

The minimum size of the window’s content view.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

contentRectForFrameRect:

Returns the window’s content rectangle with a given frame rectangle.

- (NSRect)contentRectForFrameRect:(NSRect)windowFrame
Parameters
windowFrame

The frame rectangle for the window expressed in screen coordinates.

Return Value

The window’s content rectangle, expressed in screen coordinates, with windowFrame.

Discussion

The window uses its current style mask in computing the content rectangle. See “Window Style Masks” for a list of style mask values. The main advantage of this instance-method counterpart to contentRectForFrameRect:styleMask: is that it allows you to take toolbars into account when converting between content and frame rectangles. (The toolbar is not included in the content rectangle.)

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

contentResizeIncrements

Returns the window’s content-view resizing increments.

- (NSSize)contentResizeIncrements
Return Value

The window’s content-view resizing increments.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

contentView

Returns the window’s content view, the highest accessible NSView object in the window’s view hierarchy.

- (id)contentView
Return Value

The content view.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

convertBaseToScreen:

Converts a given point from the window’s base coordinate system to the screen coordinate system. (Deprecated. Use convertRectToScreen: instead.)

- (NSPoint)convertBaseToScreen:(NSPoint)point
Parameters
point

The point expressed in the window’s base coordinate system.

Return Value

point expressed in screen coordinates.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

convertRectFromBacking:

Converts a rect from its pixel aligned backing store coordinate system to the window’s coordinate system.

- (NSRect)convertRectFromBacking:(NSRect)aRect
Parameters
aRect

The rect in the pixel backing store aligned coordinate system.

Return Value

A rect in the window’s coordinate system.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindow.h

convertRectFromScreen:

Converts the rectangle from the screen coordinate system to the window’s coordinate system

- (NSRect)convertRectFromScreen:(NSRect)aRect
Parameters
aRect

A rectangle in the screen’s coordinate system.

Return Value

A rectangle in the window’s coordinate system.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindow.h

convertRectToBacking:

Converts a rectangle from the window’s coordinate system to its pixel aligned backing store coordinate system.

- (NSRect)convertRectToBacking:(NSRect)aRect
Parameters
aRect

A rectangle in the window’s coordinate system.

Return Value

A rectangle in its pixel aligned backing store coordinate system.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindow.h

convertRectToScreen:

Converts the rectangle to the screen coordinate system from the window’s coordinate system.

- (NSRect)convertRectToScreen:(NSRect)aRect
Parameters
aRect

A rectangle in the window’s coordinate system.

Return Value

A rectangle in the screen’s coordinate system.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindow.h

convertScreenToBase:

Converts a given point from the screen coordinate system to the window’s base coordinate system. (Deprecated. Use convertRectFromScreen: instead.)

- (NSPoint)convertScreenToBase:(NSPoint)aPoint
Parameters
point

The point expressed in screen coordinates.

Return Value

point expressed in the window’s base coordinate system.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

currentEvent

Returns the event currently being processed by the application, by invoking NSApplication’s currentEvent method.

- (NSEvent *)currentEvent
Return Value

The event being processed by the application.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

dataWithEPSInsideRect:

Returns EPS data that draws the region of the window within a given rectangle.

- (NSData *)dataWithEPSInsideRect:(NSRect)rect
Parameters
rect

A rectangle (expressed in the window’s coordinate system) that identifies the region to be expressed as EPS data.

Return Value

The region in the window (identified by rect) as EPS data.

Discussion

This data can be placed on a pasteboard, written to a file, or used to create an NSImage object.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

dataWithPDFInsideRect:

Returns PDF data that draws the region of the window within a given rectangle.

- (NSData *)dataWithPDFInsideRect:(NSRect)rect
Parameters
rect

A rectangle (expressed in the window’s coordinate system) that identifies the region to be expressed as PDF data.

Return Value

The region in the window (identified by rect) as PDF data.

Discussion

This data can be placed on a pasteboard, written to a file, or used to create an NSImage object.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

deepestScreen

Returns the deepest screen the window is on (it may be split over several screens).

- (NSScreen *)deepestScreen
Return Value

The deepest screen the window is on; nil when the window is offscreen.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

defaultButtonCell

Returns the button cell that performs as if clicked when the window receives a Return (or Enter) key event.

- (NSButtonCell *)defaultButtonCell
Return Value

The button cell.

Discussion

This cell draws itself as the focal element for keyboard interface control, unless another button cell is focused on, in which case the default button cell temporarily draws itself as normal and disables its key equivalent.

The window receives a Return key event if no responder in its responder chain claims it, or if the user presses the Control key along with the Return key.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

delegate

Returns the window’s delegate.

- (id < NSWindowDelegate >)delegate
Return Value

The window’s delegate, or nil if it doesn’t have a delegate.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

deminiaturize:

De-minimizes the window.

- (void)deminiaturize:(id)sender
Parameters
sender

The message’s sender.

Discussion

Invoke this method to programmatically deminimize a minimized window in the Dock.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

depthLimit

Returns the depth limit of the window.

- (NSWindowDepth)depthLimit
Return Value

Depth limit of the window.

Discussion

The value returned can be examined with the Application Kit functions NSPlanarFromDepth, NSColorSpaceFromDepth, NSBitsPerSampleFromDepth, and NSBitsPerPixelFromDepth.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

deviceDescription

Returns a dictionary containing information about the window’s resolution.

- (NSDictionary *)deviceDescription
Return Value

A dictionary containing resolution information about the window, such as color, depth, and so on.

Discussion

This information is useful for tuning images and colors to the window’s display capabilities. The contents of the dictionary are described in “Display Device—Descriptions”.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

disableCursorRects

Disables all cursor rectangle management within the window.

- (void)disableCursorRects
Discussion

Use this method when you need to do some special cursor manipulation and you don’t want the Application Kit interfering.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

disableFlushWindow

Disables the flushWindow method for the window.

- (void)disableFlushWindow
Discussion

If the window is buffered, disabling flushWindow prevents drawing from being automatically flushed by the NSView display... methods from the window’s backing store to the screen. This method permits several views to be drawn before the results are shown to the user.

Flushing should be disabled only temporarily, while the window’s display is being updated. Each disableFlushWindow message must be paired with a subsequent enableFlushWindow message. Invocations of these methods can be nested; flushing isn’t reenabled until the last enableFlushWindow message is sent.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

disableKeyEquivalentForDefaultButtonCell

Disables the default button cell’s key equivalent, so it doesn’t perform a click when the user presses Return (or Enter).

- (void)disableKeyEquivalentForDefaultButtonCell
Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

disableScreenUpdatesUntilFlush

Disables the window’s screen updates until the window is flushed.

- (void)disableScreenUpdatesUntilFlush
Discussion

This method can be invoked to synchronize hardware surface flushes with the window’s flushes. The window immediately disables screen updates using the NSDisableScreenUpdates function and reenables screen updates when the window flushes. Sending this message multiple times during a window update cycle has no effect.

To ensure that screen updates are reenabled in a timely manner, it’s crucial that the window is marked as needing display and that the display will occur soon (that is, within the next second). When you invoke disableScreenUpdatesUntilFlush, you can make sure that a marked window gets displayed by returning control to the run loop on the main thread or by sending the window displayIfNeeded or display. If it’s unclear whether the window is marked as needing display, you can also ensure that a display occurs by using setNeedsDisplayInRect: for a view that’s visible in the window.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
NSWindow.h

disableSnapshotRestoration

Disable snapshot restoration.

- (void)disableSnapshotRestoration
Discussion

While snapshot restoration is disabled, the window will not be snapshotted for restorable state.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindowRestoration.h

discardCachedImage

Discards all of the window’s cached image rectangles.

- (void)discardCachedImage
Discussion

An NSWindow object automatically discards its cached image rectangles when it displays.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

discardCursorRects

Invalidates all cursor rectangles in the window.

- (void)discardCursorRects
Discussion

This method is invoked by resetCursorRects to clear out existing cursor rectangles before resetting them. You shouldn’t invoke it in the code you write, but you might want to override it to change its behavior.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

discardEventsMatchingMask:beforeEvent:

Forwards the message to the NSApplication object, NSApp.

- (void)discardEventsMatchingMask:(NSUInteger)eventMask beforeEvent:(NSEvent *)lastEvent
Parameters
eventMask

The mask of the events to discard.

lastEvent

The event up to which queued events are discarded from the queue.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

display

Passes a display message down the window’s view hierarchy, thus redrawing all views within the window, including the frame view that draws the border, title bar, and other peripheral elements.

- (void)display
Discussion

You rarely need to invoke this method. NSWindow objects normally record which of their views need display and display them automatically on each pass through the event loop.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

displayIfNeeded

Passes a displayIfNeeded message down the window’s view hierarchy, thus redrawing all views that need to be displayed, including the frame view that draws the border, title bar, and other peripheral elements.

- (void)displayIfNeeded
Discussion

This method is useful when you want to modify some number of views and then display only the ones that were modified.

You rarely need to invoke this method. NSWindow objects normally record which of their views need display and display them automatically on each pass through the event loop.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

displaysWhenScreenProfileChanges

Indicates whether the window context should be updated when the screen profile changes or when the window moves to a different screen.

- (BOOL)displaysWhenScreenProfileChanges
Return Value

YES when the window context should be updated when the screen profile changes or when the window moves to a different screen; otherwise, NO.

Discussion

The default value is NO.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSWindow.h

dockTile

Provides the application’s Dock tile.

- (NSDockTile *)dockTile
Return Value

The application’s Dock tile.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

dragImage:at:offset:event:pasteboard:source:slideBack:

Begins a dragging session.

- (void)dragImage:(NSImage *)image at:(NSPoint)imageLocation offset:(NSSize)pointerOffset event:(NSEvent *)event pasteboard:(NSPasteboard *)pasteboard source:(id)sourceObject slideBack:(BOOL)slideBack
Parameters
image

The object to be dragged.

imageLocation

Location of the image’s bottom-left corner in the window’s coordinate system. It determines the placement of the dragged image under the pointer.

initialOffset

The pointer’s location relative to the mouse-down location. Not used in OS X v10.4 and later.

event

The left-mouse down event that triggered the dragging operation.

pasteboard

The pasteboard that holds the data to be transferred to the destination.

sourceObject

The object serving as the controller of the dragging operation. It must conform to the NSDraggingSource protocol.

slideBack

Specifies whether the drag image should slide back to imageLocation if it's rejected by the drag destination. Pass YES to specify slide back behavior or NO to specify that it should not.

Discussion

This method should be invoked only from within a view’s implementation of the mouseDown: or mouseDragged: methods (which overrides the version defined in NSResponder class). Essentially the same as the NSView method of the same name, except that imageLocation is given in the NSWindow object’s base coordinate system.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

drawers

Returns the collection of drawers associated with the window.

- (NSArray *)drawers
Return Value

The collection of drawers associated with the window.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDrawer.h

enableCursorRects

Reenables cursor rectangle management within the window after a disableCursorRects message.

- (void)enableCursorRects
Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

enableFlushWindow

Reenables the flushWindow method for the window after it was disabled through a previous disableFlushWindow message.

- (void)enableFlushWindow
Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

enableKeyEquivalentForDefaultButtonCell

Reenables the default button cell’s key equivalent, so it performs a click when the user presses Return (or Enter).

- (void)enableKeyEquivalentForDefaultButtonCell
Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

enableSnapshotRestoration

Enable snapshot restoration.

- (void)enableSnapshotRestoration
Discussion

While snapshot restoration is enabled, the window will be snapshotted for restorable state.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindowRestoration.h

endEditingFor:

Forces the field editor to give up its first responder status and prepares it for its next assignment.

- (void)endEditingFor:(id)object
Parameters
object

The object that is using the window’s field editor.

Discussion

If the field editor is the first responder, it’s made to resign that status even if its resignFirstResponder method returns NO. This registration forces the field editor to send a textDidEndEditing: message to its delegate. The field editor is then removed from the view hierarchy, its delegate is set to nil, and it’s emptied of any text it may contain.

This method is typically invoked by the object using the field editor when it’s finished. Other objects normally change the first responder by simply using makeFirstResponder:, which allows a field editor or other object to retain its first responder status if, for example, the user has entered an invalid value. The endEditingFor: method should be used only as a last resort if the field editor refuses to resign first responder status. Even in this case, you should always allow the field editor a chance to validate its text and take whatever other action it needs first. You can do this by first trying to make the NSWindow object the first responder:

if ([myWindow makeFirstResponder:myWindow]) {
    /* All fields are now valid; it’s safe to use fieldEditor:forObject:
        to claim the field editor. */
}
else {
    /* Force first responder to resign. */
    [myWindow endEditingFor:nil];
}
Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

endSheet:

Ends a document-modal session and dismisses the specified sheet.

- (void)endSheet:(NSWindow *)sheetWindow
Parameters
sheetWindow

The window object that represents the sheet to be dismissed.

Discussion

This method ends the modal session with the return code NSModalResponseStop.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSWindow.h

endSheet:returnCode:

Ends a document-modal session and dismisses the specified sheet.

- (void)endSheet:(NSWindow *)sheetWindow returnCode:(NSModalResponse)returnCode
Parameters
sheetWindow

The window object that represents the sheet to dismiss.

returnCode

The return code to send to the completion handler. You can use a custom value that you define or one of the return codes defined in the NSModalResponse enumeration or “Additional NSModalResponse Values.”

Discussion

This method ends the modal session with the specified return code.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSWindow.h

fieldEditor:forObject:

Returns the window’s field editor, creating it if requested.

- (NSText *)fieldEditor:(BOOL)createWhenNeeded forObject:(id)anObject
Parameters
createWhenNeeded

If YES, creates a field editor if one doesn’t exist; if NO, does not create a field editor.

A freshly created NSWindow object doesn’t have a field editor. After a field editor has been created for a window, the createWhenNeeded argument is ignored. By passing NO for createWhenNeeded and testing the return value, however, you can predicate an action on the existence of the field editor.

anObject

A text-displaying object for which the delegate (in windowWillReturnFieldEditor:toObject:) assigns a custom field editor. Pass nil to get the default field editor, which can be the NSWindow field editor or a custom field editor returned by the delegate.

Return Value

Returns the field editor for the designated object (anObject) or, if anObject is nil, the default field editor. Returns nil if createFlag is NO and if the field editor doesn’t exist.

Discussion

The field editor is a single NSTextView object that is shared among all the controls in a window for light text-editing needs. It is automatically instantiated when needed, and it can be used however your application sees fit. Typically, the field editor is used by simple text-bearing objects—for example, an NSTextField object uses its window’s field editor to display and manipulate text. The field editor can be shared by any number of objects, and so its state may be constantly changing. Therefore, it shouldn’t be used to display text that demands sophisticated layout (for this you should create a dedicated NSTextView object).

The field editor may be in use by some view object, so be sure to properly dissociate it from that object before actually using it yourself (the appropriate way to do this is illustrated in the description of endEditingFor:). Once you retrieve the field editor, you can insert it in the view hierarchy, set a delegate to interpret text events, and have it perform whatever editing is needed. Then, when it sends a textDidEndEditing: message to the delegate, you can get its text to display or store and remove the field editor using endEditingFor:.

The window’s delegate can substitute a custom field editor in place of the window’s field editor by implementing windowWillReturnFieldEditor:toObject:. The custom field editor can become the default editor (common to all text-displaying objects) or specific to a particular text-displaying object (anObject). The window sends this message to its delegate with itself and anObject as the arguments; if the delegate returns a non-nil value, the window returns that object instead of its field editor in fieldEditor:forObject:. However, note the following:

  • If the window’s delegate is identical to anObject, windowWillReturnFieldEditor:toObject: isn’t sent to the delegate.

  • The object returned by the delegate method, though it may become first responder, does not become the window's default field editor. Other objects continue to use the window's default field editor.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

firstResponder

Returns the window’s first responder.

- (NSResponder *)firstResponder
Return Value

The first responder.

Discussion

The first responder is usually the first object in a responder chain to receive an event or action message. In most cases, the first responder is a view object in that the user selects or activates with the mouse or keyboard.

You can use the firstResponder method in custom subclasses of responder classes (NSWindow, NSApplication, NSView, and subclasses) to determine if an instance of the subclass is currently the first responder. You can also use it to help locate a text field that currently has first-responder status. For more on this subject, see ““Event Handling Basics”.“

In OS X v10.6 and later, firstResponder is key-value observing compliant.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

flushWindow

Flushes the window’s offscreen buffer to the screen if the window is buffered and flushing is enabled.

- (void)flushWindow
Discussion

Does nothing for other display devices, such as a printer. This method is automatically invoked by the NSWindow display and displayIfNeeded methods and the corresponding NSView display and displayIfNeeded methods.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

flushWindowIfNeeded

Flushes the window’s offscreen buffer to the screen if flushing is enabled and if the last flushWindow message had no effect because flushing was disabled.

- (void)flushWindowIfNeeded
Discussion

To avoid unnecessary flushing, use this method rather than flushWindow to flush an NSWindow object after flushing has been reenabled.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

frame

Returns the window’s frame rectangle.

- (NSRect)frame
Return Value

The frame rectangle of the window in screen coordinates, including the title bar.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

frameAutosaveName

Returns the name used to automatically save the window’s frame rectangle data in the defaults system, as set through setFrameAutosaveName:.

- (NSString *)frameAutosaveName
Return Value

The name used to save the window’s frame rectangle automatically in the defaults system.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

frameRectForContentRect:

Returns the window’s frame rectangle with a given content rectangle.

- (NSRect)frameRectForContentRect:(NSRect)windowContent
Parameters
windowContent

The content rectangle for the window expressed in screen coordinates.

Return Value

The window’s frame rectangle, expressed in screen coordinates, with windowContent.

Discussion

The window uses its current style mask in computing the frame rectangle. See “Window Style Masks” for a list of style mask values. The major advantage of this instance-method counterpart to frameRectForContentRect:styleMask: is that it allows you to take toolbars into account when converting between content and frame rectangles. (The toolbar is included in the frame rectangle but not the content rectangle.)

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

graphicsContext

Provides the graphics context associated with the window for the current thread.

- (NSGraphicsContext *)graphicsContext
Return Value

The graphics context associated with the window for the current thread.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
NSWindow.h

gState

Returns the window’s graphics state object.

- (NSInteger)gState
Return Value

The graphics state object associated with the window.

Discussion

This graphics state is used by default for all NSView objects in the window’s view hierarchy, but individual views can be made to use their own with the NSView method allocateGState.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

hasDynamicDepthLimit

Indicates whether the window’s depth limit can change to match the depth of the screen it’s on.

- (BOOL)hasDynamicDepthLimit
Return Value

YES when the window has a dynamic depth limit; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

hasShadow

Indicates whether the window has a shadow.

- (BOOL)hasShadow
Return Value

YES when the window has a shadow; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

hidesOnDeactivate

Indicates whether the window is removed from the screen when its application becomes inactive.

- (BOOL)hidesOnDeactivate
Return Value

YES if the window is removed from the screen when its application is deactivated; NO if it remains onscreen.

Discussion

The default for NSWindow is NO; the default for NSPanel is YES.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

ignoresMouseEvents

Indicates whether the window is transparent to mouse events.

- (BOOL)ignoresMouseEvents
Return Value

YES when the window is transparent to mouse events; otherwise, NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSWindow.h

initialFirstResponder

Returns view that’s made first responder the first time the window is placed onscreen.

- (NSView *)initialFirstResponder
Return Value

The view that’s made first responder the first time the window is placed onscreen.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

initWithContentRect:styleMask:backing:defer:

Initializes the window with the specified values.

- (id)initWithContentRect:(NSRect)contentRect styleMask:(NSUInteger)windowStyle backing:(NSBackingStoreType)bufferingType defer:(BOOL)deferCreation
Parameters
contentRect

Origin and size of the window’s content area in screen coordinates. Note that the window server limits window position coordinates to ±16,000 and sizes to 10,000.

windowStyle

The window’s style. It can be NSBorderlessWindowMask, or it can contain any of the options described in “Window Style Masks,” combined using the C bitwise OR operator. Borderless windows display none of the usual peripheral elements and are generally useful only for display or caching purposes; you should normally not need to create them. Also, note that a window’s style mask should include NSTitledWindowMask if it includes any of the others.

bufferingType

Specifies how the drawing done in the window is buffered by the window device, and possible values are described in “NSBackingStoreType—Buffered Window Drawing.”

deferCreation

Specifies whether the window server creates a window device for the window immediately. When YES, the window server defers creating the window device until the window is moved onscreen. All display messages sent to the window or its views are postponed until the window is created, just before it’s moved onscreen.

Return Value

The initialized window.

Discussion

This method is the designated initializer for the NSWindow class.

Deferring the creation of the window improves launch time and minimizes the virtual memory load on the window server.

The new window creates a view to be its default content view. You can replace it with your own object by using the setContentView: method.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

initWithContentRect:styleMask:backing:defer:screen:

Initializes an allocated window with the specified values.

- (id)initWithContentRect:(NSRect)contentRect styleMask:(NSUInteger)windowStyle backing:(NSBackingStoreType)bufferingType defer:(BOOL)deferCreation screen:(NSScreen *)screen
Parameters
contentRect

Origin and size of the window’s content area in screen coordinates. The origin is relative to the origin of the provided screen. Note that the window server limits window position coordinates to ±16,000 and sizes to 10,000.

windowStyle

The window’s style. It can be NSBorderlessWindowMask, or it can contain any of the options described in “Window Style Masks,” combined using the C bitwise OR operator. Borderless windows display none of the usual peripheral elements and are generally useful only for display or caching purposes; you should not usually need to create them. Also, note that a window’s style mask should include NSTitledWindowMask if it includes any of the others.

bufferingType

Specifies how the drawing done in the window is buffered by the window device; possible values are described in “NSBackingStoreType—Buffered Window Drawing.”

deferCreation

Specifies whether the window server creates a window device for the window immediately. When YES, the window server defers creating the window device until the window is moved onscreen. All display messages sent to the window or its views are postponed until the window is created, just before it’s moved onscreen.

screen

Specifies the screen on which the window is positioned. The content rectangle is positioned relative to the bottom-left corner of screen. When nil, the content rectangle is positioned relative to (0, 0), which is the origin of the primary screen.

Return Value

The initialized window.

Discussion

The primary screen is the one that contains the current key window or, if there is no key window, the one that contains the main menu. If there’s neither a key window nor a main menu (if there’s no active application), the primary screen is the one where the origin of the screen coordinate system is located.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

initWithWindowRef:

Returns a Cocoa window created from a Carbon window.

- (NSWindow *)initWithWindowRef:(void *)carbonWindowRef
Parameters
carbonWindowRef

The Carbon WindowRef object to use to create the Cocoa window.

Return Value

A Cocoa window created from carbonWindowRef.

Discussion

For more information on Carbon-Cocoa integration, see “Using a Carbon User Interface in a Cocoa Application” in Carbon-Cocoa Integration Guide.

Special Considerations

For historical reasons, contrary to normal memory management policy initWithWindowRef: does not retain windowRef. It is therefore recommended that you make sure you retain windowRef before calling this method. If windowRef is still valid when the Cocoa window is deallocated, the Cocoa window will release it.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

inLiveResize

Indicates whether the window is being resized by the user.

- (BOOL)inLiveResize
Return Value

YES if the window is being live resized; otherwise, NO.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

invalidateCursorRectsForView:

Marks as invalid the cursor rectangles of a given NSView object in the window’s view hierarchy, so they’ll be set up again when the window becomes key (or immediately if the window is key).

- (void)invalidateCursorRectsForView:(NSView *)view
Parameters
view

The view in the window’s view hierarchy.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

invalidateShadow

Invalidates the window shadow so that it is recomputed based on the current window shape.

- (void)invalidateShadow
Availability
  • Available in OS X v10.2 and later.
Declared In
NSWindow.h

isAutodisplay

Indicates whether the window automatically displays views that need to be displayed.

- (BOOL)isAutodisplay
Return Value

YES when the window automatically displays views that need to be displayed; otherwise, NO.

Discussion

Automatic display typically occurs on each pass through the event loop.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

isDocumentEdited

Indicates whether the window’s document has been edited.

- (BOOL)isDocumentEdited
Return Value

YES when the window’s document has been edited; otherwise, NO.

Discussion

Initially, by default, NSWindow objects are in the “not edited” state.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

isExcludedFromWindowsMenu

Indicates whether the window is excluded from the application’s Windows menu.

- (BOOL)isExcludedFromWindowsMenu
Return Value

YES when the window is excluded from the Windows menu; otherwise, NO.

Discussion

The default initial setting is NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

isFlushWindowDisabled

Indicates whether the window’s flushing ability is disabled.

- (BOOL)isFlushWindowDisabled
Return Value

YES when the window’s flushing ability has been disabled; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

isKeyWindow

Indicates whether the window is the key window for the application.

- (BOOL)isKeyWindow
Return Value

YES if the window is the key window for the application; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

isMainWindow

Indicates whether the window is the application’s main window.

- (BOOL)isMainWindow
Return Value

YES when the window is the main window for the application; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

isMiniaturized

Indicates whether the window is minimized.

- (BOOL)isMiniaturized
Return Value

YES if the window is minimized; otherwise, NO.

Discussion

A minimized window is removed from the screen and replaced by a image, icon, or button that represents it, called the counterpart.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

isMovable

Indicates whether the window can be moved by clicking in its title bar or background.

- (BOOL)isMovable
Return Value

YES if the window can be moved by the user; otherwise, NO.

Discussion

setMovableByWindowBackground:, called with the argument YES, is ignored by a window that returns NO from isMovable. If a window returns NO, that means it can only be dragged between spaces in F8 mode, and its relative screen position is always preserved. Note that a resizable window may still be resized, and the window frame may be changed programmatically. A non-movable window will not be moved or resized by the system in response to a display reconfiguration. Applications may choose to enable application-controlled window dragging after disabling user-initiating dragging by handling the mouseDown:/mouseDragged:/mouseUp: sequence in sendEvent: in an NSWindow subclass.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

isMovableByWindowBackground

Indicates whether the window is movable by clicking and dragging anywhere in its background.

- (BOOL)isMovableByWindowBackground
Return Value

YES when the window is movable by clicking and dragging anywhere in its background; otherwise, NO.

Discussion

A window with a style mask of NSTexturedBackgroundWindowMask is movable by background by default. Sheets and drawers cannot be movable by window background.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSWindow.h

isOnActiveSpace

Indicates whether the window is on the currently active space.

- (BOOL)isOnActiveSpace
Return Value

YES if the window is on the currently active space; otherwise, NO.

Discussion

For visible windows, this method indicates whether the window is currently visible on the active space. For non-visible windows, it indicates whether ordering the window onscreen would cause it to be on the active space.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

isOneShot

Indicates whether the window device the window manages is freed when it’s removed from the screen list.

- (BOOL)isOneShot
Return Value

YES when the window’s window device is freed when it’s removed from the screen list; otherwise, NO.

Discussion

The default is NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

isOpaque

Indicates whether the window is opaque.

- (BOOL)isOpaque
Return Value

YES when the window is opaque; otherwise, NO.

Discussion

The default is YES.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

isReleasedWhenClosed

Indicates whether the window is released when it receives the close message.

- (BOOL)isReleasedWhenClosed
Return Value

YES if the window is automatically released after being closed; NO if it’s simply removed from the screen.

Discussion

The default for NSWindow is YES; the default for NSPanel is NO. Release when closed, however, is ignored for windows owned by window controllers.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

isRestorable

Returns a Boolean value indicating whether the window configuration is preserved between application launches.

- (BOOL)isRestorable
Return Value

YES if the window configuration is preserved or NO if it is not.

Discussion

By default, this method returns YES if the window’s styleMask property includes the NSTitledWindowMask flag. For other windows, this method returns NO. Specifying a value explicitly using the setRestorable: method overrides the default values.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindowRestoration.h

isSheet

Indicates whether the window has ever run as a modal sheet.

- (BOOL)isSheet
Return Value

YES if the window has ever run as a modal sheet; otherwise, NO.

Availability
  • Available in OS X v10.1 and later.
Declared In
NSWindow.h

isVisible

Indicates whether the window is visible onscreen (even when It’s obscured by other windows).

- (BOOL)isVisible
Return Value

YES when the window is onscreen (even if it’s obscured by other windows); otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

isZoomed

Returns a Boolean value that indicates whether the window is in a zoomed state.

- (BOOL)isZoomed
Return Value

YES if the window is in a zoomed state; otherwise, NO.

Discussion

The zoomed state of the window is determined using the following steps:

  1. If the delegate or the window class implements windowWillUseStandardFrame:defaultFrame:, it is invoked to obtain the zoomed frame of the window. The result of isZoomed is then determined by whether or not the current window frame is equal to the zoomed frame.

  2. If the neither the delegate nor the window class implements windowWillUseStandardFrame:defaultFrame:, a default frame that nearly fits the screen is chosen. If the delegate or window class implements , it is invoked to validate the proposed zoomed frame. Once the zoomed frame is validated, the result of isZoomed is determined by whether or not the current window frame is equal to the zoomed frame.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

keyDown:

Handles a given keyboard event that may need to be interpreted as changing the key view or triggering a keyboard equivalent.

- (void)keyDown:(NSEvent *)event
Parameters
event

The keyboard event to process.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

keyViewSelectionDirection

Returns the direction the window is currently using to change the key view.

- (NSSelectionDirection)keyViewSelectionDirection
Return Value

The direction the window is using to change the key view.

Discussion

This direction can be one of the values described in “NSSelectionDirection—Direction of Key View Change.”

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

layoutIfNeeded

Updates the layout of views in the window based on the current views and constraints.

- (void)layoutIfNeeded
Discussion

Before displaying a window that uses constraints-based layout the system invokes this method to ensure that the layout of all views is up to date. This method updates the layout if needed, first invoking updateConstraintsIfNeeded to ensure that all constraints are up to date. This method is called automatically by the system, but may be invoked manually if you need to examine the most up to date layout.

Subclasses should not override this method.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

level

Returns the window level of the window.

- (NSInteger)level
Return Value

The window level.

Discussion

See “Window Levels” for a list of possible values.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

makeFirstResponder:

Attempts to make a given responder the first responder for the window.

- (BOOL)makeFirstResponder:(NSResponder *)responder
Parameters
responder

The responder to set as the window’s first responder. nil makes the window its first responder.

Return Value

YES when the operation is successful; otherwise, NO.

Discussion

If responder isn’t already the first responder, this method first sends a resignFirstResponder message to the object that is the first responder. If that object refuses to resign, it remains the first responder, and this method immediately returns NO. If the current first responder resigns, this method sends a becomeFirstResponder message to responder. If responder does not accept first responder status, the NSWindow object becomes first responder; in this case, the method returns YES even if responder refuses first responder status.

If responder is nil, this method still sends resignFirstResponder to the current first responder. If the current first responder refuses to resign, it remains the first responder and this method immediately returns NO. If the current first responder returns YES from resignFirstResponder, the window is made its own first responder and this method returns YES.

The Application Kit framework uses this method to alter the first responder in response to mouse-down events; you can also use it to explicitly set the first responder from within your program. The responder object is typically an NSView object in the window’s view hierarchy. If this method is called explicitly, first send acceptsFirstResponder to responder, and do not call makeFirstResponder: if acceptsFirstResponder returns NO.

Use setInitialFirstResponder: to the set the first responder to be used when the window is brought onscreen for the first time.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

makeKeyAndOrderFront:

Moves the window to the front of the screen list, within its level, and makes it the key window; that is, it shows the window.

- (void)makeKeyAndOrderFront:(id)sender
Parameters
sender

The message’s sender.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

makeKeyWindow

Makes the window the key window.

- (void)makeKeyWindow
Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

makeMainWindow

Makes the window the main window.

- (void)makeMainWindow
Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

maxSize

Returns the maximum size to which the window’s frame (including its title bar) can be sized.

- (NSSize)maxSize
Return Value

The maximum size to which the window’s frame (including its title bar) can be sized either by the user or by the setFrame... methods other than setFrame:display: and setFrame:display:animate:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

miniaturize:

Removes the window from the screen list and displays the minimized window in the Dock.

- (void)miniaturize:(id)sender
Parameters
sender

The message’s sender.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

miniwindowImage

Returns the custom miniaturized window image of the window.

- (NSImage *)miniwindowImage
Return Value

The custom miniaturized window image.

Discussion

The miniaturized window image is the image displayed in the Dock when the window is minimized. If you did not assign a custom image to the window, this method returns nil.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

miniwindowTitle

Returns the title displayed in the window’s minimized window.

- (NSString *)miniwindowTitle
Return Value

The title displayed in the window’s minimized window.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

minSize

Returns the minimum size to which the window’s frame (including its title bar) can be sized.

- (NSSize)minSize
Return Value

The minimum size to which the window’s frame (including its title bar) can be sized either by the user or by the setFrame... methods other than setFrame:display: and setFrame:display:animate:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

mouseLocationOutsideOfEventStream

Returns the current location of the pointer reckoned in the window’s base coordinate system.

- (NSPoint)mouseLocationOutsideOfEventStream
Return Value

The current location of the pointer reckoned in the window’s base coordinate system, regardless of the current event being handled or of any events pending.

Discussion

For the same information in screen coordinates, use NSEvent's mouseLocation.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

nextEventMatchingMask:

Returns the next event matching a given mask.

- (NSEvent *)nextEventMatchingMask:(NSUInteger)eventMask
Parameters
eventMask

The mask that the event to return must match. Events with non-matching masks are left in the queue. See discardEventsMatchingMask:beforeEvent: in NSApplication for the list of mask values.

Return Value

The next event whose mask matches eventMask; nil when no matching event was found.

Discussion

This method sends the message nextEventMatchingMask:eventMask untilDate:[NSDate distantFuture] inMode:NSEventTrackingRunLoopMode dequeue:YES to the application (NSApp).

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

nextEventMatchingMask:untilDate:inMode:dequeue:

Forwards the message to the global NSApplication object, NSApp.

- (NSEvent *)nextEventMatchingMask:(NSUInteger)eventMask untilDate:(NSDate *)expirationDate inMode:(NSString *)runLoopMode dequeue:(BOOL)dequeue
Parameters
eventMask

The mask that the event to return must match.

expirationDate

The date until which to wait for events.

runLoopMode

The run loop mode to use while waiting for events

dequeue

YES to remove the returned event from the event queue; NO to leave the returned event in the queue.

Return Value

The next event whose mask matches eventMask; nil when no matching event was found.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

occlusionState

Returns the occlusion state of the window.

- (NSWindowOcclusionState)occlusionState
Return Value

If occlusionState is NSWindowOcclusionStateVisible, at least part of the window is visible; otherwise, the window is fully occluded.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSWindow.h

orderBack:

Moves the window to the back of its level in the screen list, without changing either the key window or the main window.

- (void)orderBack:(id)sender
Parameters
sender

Message originator.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

orderFront:

Moves the window to the front of its level in the screen list, without changing either the key window or the main window.

- (void)orderFront:(id)sender
Parameters
sender

The message’s sender.

Discussion

The default animation based on the window type will be used when the window is ordered front unless it has been modified by the setAnimationBehavior: method.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

orderFrontRegardless

Moves the window to the front of its level, even if its application isn’t active, without changing either the key window or the main window.

- (void)orderFrontRegardless
Parameters
sender

The message’s sender.

Discussion

Normally an NSWindow object can’t be moved in front of the key window unless it and the key window are in the same application. You should rarely need to invoke this method; it’s designed to be used when applications are cooperating in such a way that an active application (with the key window) is using another application to display data.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

orderOut:

Removes the window from the screen list, which hides the window.

- (void)orderOut:(id)sender
Parameters
sender

The message’s sender.

Discussion

If the window is the key or main window, the NSWindow object immediately behind it is made key or main in its place. Calling the orderOut: method causes the window to be removed from the screen, but does not cause it to be released. See the close method for information on when a window is released.

The default animation based on the window type will be used when the window is ordered out unless it has been modified by the setAnimationBehavior: method.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

orderWindow:relativeTo:

Repositions the window’s window device in the window server’s screen list.

- (void)orderWindow:(NSWindowOrderingMode)orderingMode relativeTo:(NSInteger)otherWindowNumber
Parameters
orderingMode
  • NSWindowOut: The window is removed from the screen list and otherWindowNumber is ignored.

  • NSWindowAbove: The window is ordered immediately in front of the window whose window number is otherWindowNumber

  • NSWindowBelow: The window is placed immediately behind the window represented by otherWindowNumber.

otherWindowNumber

The number of the window the window is to be placed in front of or behind. Pass 0 to place the window in front of (when orderingMode is NSWindowAbove) or behind (when orderingMode is NSWindowBelow) all other windows in its level.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

parentWindow

Returns the parent window to which the window is attached as a child.

- (NSWindow *)parentWindow
Return Value

The window to which the window is attached as a child.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
NSWindow.h

performClose:

This action method simulates the user clicking the close button by momentarily highlighting the button and then closing the window.

- (void)performClose:(id)sender
Parameters
sender

The message’s sender.

Discussion

If the window’s delegate or the window itself implements windowShouldClose:, that message is sent with the window as the argument. (Only one such message is sent; if both the delegate and the NSWindow object implement the method, only the delegate receives the message.) If the windowShouldClose: method returns NO, the window isn’t closed. If it returns YES, or if it isn’t implemented, performClose: invokes the close method to close the window.

If the window doesn’t have a close button or can’t be closed (for example, if the delegate replies NO to a windowShouldClose: message), the system emits the alert sound.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

performMiniaturize:

Simulates the user clicking the minimize button by momentarily highlighting the button, then minimizing the window.

- (void)performMiniaturize:(id)sender
Parameters
sender

The message’s sender.

Discussion

If the window doesn’t have a minimize button or can’t be minimized for some reason, the system emits the alert sound.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

performZoom:

This action method simulates the user clicking the zoom box by momentarily highlighting the button and then zooming the window.

- (void)performZoom:(id)sender
Parameters
sender

The object sending the message.

Discussion

If the window doesn’t have a zoom box or can’t be zoomed for some reason, the computer beeps.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

postEvent:atStart:

Forwards the message to the global NSApplication object, NSApp.

- (void)postEvent:(NSEvent *)event atStart:(BOOL)atStart
Parameters
event

The event to add to the window’s event queue.

atStart

YES to place the event in the front of the queue; NO to place it in the back.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

preferredBackingLocation

Indicates the preferred location for the window’s backing store.

- (NSWindowBackingLocation)preferredBackingLocation
Return Value

The preferred location for the window’s backing store. See “Constants” for possible values.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

preservesContentDuringLiveResize

Returns whether the window tries to optimize user-initiated resize operations by preserving the content of views that have not changed.

- (BOOL)preservesContentDuringLiveResize
Return Value

YES if the window tries to optimize live resize operations by preserving the content of views that have not moved; otherwise, NO.

Discussion

When live-resize optimization is active, the window redraws only those views that moved (or do not support this optimization) during a live resize operation.

See preservesContentDuringLiveResize in NSView for additional information on how to support this optimization.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSWindow.h

preventsApplicationTerminationWhenModal

Indicates whether the window prevents application termination when modal.

- (BOOL)preventsApplicationTerminationWhenModal
Return Value

YES if the window prevents application termination when modal; otherwise, NO.

Discussion

The default value is YES.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

print:

This action method runs the Print panel, and if the user chooses an option other than canceling, prints the window (its frame view and all subviews).

- (void)print:(id)sender
Parameters
sender

The message’s sender.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

recalculateKeyViewLoop

Marks the key view loop as dirty and in need of recalculation.

- (void)recalculateKeyViewLoop
Discussion

The key view loop is actually recalculated the next time someone requests the next or previous key view of the window. The recalculated loop is based on the geometric order of the views in the window.

If you do not want to maintain the key view loop of your window manually, you can use this method to do it for you. When it is first loaded, NSWindow calls this method automatically if your window does not have a key view loop already established. If you add or remove views later, you can call this method manually to update the window’s key view loop. You can also call setAutorecalculatesKeyViewLoop: to have the window recalculate the loop automatically.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSWindow.h

registerForDraggedTypes:

Registers a give set of pasteboard types as the pasteboard types the window will accept as the destination of an image-dragging session.

- (void)registerForDraggedTypes:(NSArray *)pasteboardTypes
Parameters
pasteboardTypes

An array of the pasteboard types the window will accept as the destination of an image-dragging session.

Discussion

Registering an NSWindow object for dragged types automatically makes it a candidate destination object for a dragging session. NSWindow has a default implementation for many of the methods in the NSDraggingDestination protocol. The default implementation forwards each message to the delegate if the delegate responds to the selector of the message. The messages forwarded this way are draggingEntered:, draggingUpdated:, draggingExited:, prepareForDragOperation:, performDragOperation:, and concludeDragOperation:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

removeChildWindow:

Detaches a given child window from the window.

- (void)removeChildWindow:(NSWindow *)childWindow
Parameters
childWindow

The child window to detach.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
NSWindow.h

representedFilename

Returns the pathname of the file the window represents.

- (NSString *)representedFilename
Return Value

The path to the file of the window’s represented file.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

representedURL

Provides the URL of the file the window represents.

- (NSURL *)representedURL
Return Value

The URL for the file the window represents.

Discussion

When the URL specifies a path, the window shows an icon in its title bar, as described in Table 1.

Table 1  Title bar document icon display

File path

Document icon

Empty

None.

Specifies a nonexistent file

Generic.

Specifies an existent file

Specific for the file’s type.

You can customize the file icon in the title bar with the following code:

[[<window> standardWindowButton:NSWindowDocumentIconButton] setImage:<image>]

When the URL identifies an existing file, the window’s title offers a pop-up menu showing the path components of the URL. (The user displays this menu by Command-clicking the title.) The behavior and contents of this menu can be controlled with window:shouldPopUpDocumentPathMenu:.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

resetCursorRects

Clears the window’s cursor rectangles and the cursor rectangles of the NSView objects in its view hierarchy.

- (void)resetCursorRects
Discussion

Invokes discardCursorRects to clear the window’s cursor rectangles, then sends resetCursorRects to every NSView object in the window’s view hierarchy.

This method is typically invoked by the NSApplication object when it detects that the key window’s cursor rectangles are invalid. In program code, it’s more efficient to invoke invalidateCursorRectsForView:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

resignKeyWindow

Invoked automatically when the window resigns key window status; never invoke this method directly.

- (void)resignKeyWindow
Discussion

This method sends resignKeyWindow to the window’s first responder, sends windowDidResignKey: to the window’s delegate, and posts an NSWindowDidResignKeyNotification to the default notification center.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

resignMainWindow

Invoked automatically when the window resigns main window status; never invoke this method directly.

- (void)resignMainWindow
Discussion

This method sends windowDidResignMain: to the window’s delegate and posts an NSWindowDidResignMainNotification to the default notification center.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

resizeFlags

Returns the flags field of the event record for the mouse-down event that initiated the resizing session.

- (NSInteger)resizeFlags
Return Value

A mask indicating which of the modifier keys was held down when the mouse-down event occurred. The flags are listed in NSEvent object’s modifierFlags method description.

Discussion

This method is valid only while the window is being resized

You can use this method to constrain the direction or amount of resizing. Because of its limited validity, this method should only be invoked from within an implementation of the delegate method windowWillResize:toSize:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

resizeIncrements

Returns the window’s resizing increments.

- (NSSize)resizeIncrements
Return Value

The window’s resizing increments.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

restorationClass

Returns the restoration class associated with the window.

- (Class < NSWindowRestoration >)restorationClass
Return Value

The class object corresponding to the class to use to restore the window or nil if none is set.

Discussion

Restoration classes assist in the recreation of window objects during subsequent launches of the application. When prompted by AppKit, the restoration class creates or acquires a window that matches the same type that was preserved. It then passes that window back to AppKit, which proceeds to reconfigure the window with the preserved state information.

For multi-window document applications, this method returns the NSDocumentController class for windows that are associated with an NSDocument object by default. For other types of windows, this method returns nil by default.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindowRestoration.h

restoreCachedImage

Splices the window’s cached image rectangles, if any, back into its raster image (and buffer if it has one), undoing the effect of any drawing performed within those areas since they were established using cacheImageInRect:.

- (void)restoreCachedImage
Discussion

You must invoke flushWindow after this method to guarantee proper redisplay. An NSWindow object automatically discards its cached image rectangles when it displays.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

runToolbarCustomizationPalette:

The action method for the “Customize Toolbar…” menu item.

- (void)runToolbarCustomizationPalette:(id)sender
Parameters
sender

The message’s sender.

Discussion

See the NSToolbar class description for additional information.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

saveFrameUsingName:

Saves the window’s frame rectangle in the user defaults system under a given name.

- (void)saveFrameUsingName:(NSString *)frameName
Parameters
frameName

The name under which the frame is to be saved.

Discussion

With the companion method setFrameUsingName:, you can save and reset an NSWindow object’s frame over various launches of an application. The default is owned by the application and stored under the name "NSWindow Frame frameName". See NSUserDefaults for more information.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

screen

Returns the screen the window is on.

- (NSScreen *)screen
Return Value

The screen where most of the window is on; nil when the window is offscreen.

Discussion

When the window is partly on one screen and partly on another, the screen where most of it lies is returned.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

selectKeyViewFollowingView:

Makes key the view that follows the given view.

- (void)selectKeyViewFollowingView:(NSView *)referenceView
Parameters
referenceView

The view whose following view in the key view loop is sought.

Discussion

Sends the nextValidKeyView message to referenceView and, if that message returns an NSView object, invokes makeFirstResponder: with the returned object.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

selectKeyViewPrecedingView:

Makes key the view that precedes the given view.

- (void)selectKeyViewPrecedingView:(NSView *)referenceView
Parameters
referenceView

The view whose preceding view in the key view loop is sought.

Discussion

Sends the previousValidKeyView message to referenceView and, if that message returns an NSView object, invokes makeFirstResponder: with the returned object.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

selectNextKeyView:

This action method searches for a candidate next key view and, if it finds one, invokes makeFirstResponder: to establish it as the first responder.

- (void)selectNextKeyView:(id)sender
Parameters
sender

The message’s sender.

Discussion

The candidate is one of the following (searched for in this order):

  • The current first responder’s next valid key view, as returned by the nextValidKeyView method of NSView

  • The object designated as the window’s initial first responder (using setInitialFirstResponder:) if it returns YES to an acceptsFirstResponder message

  • Otherwise, the initial first responder’s next valid key view, which may end up being nil

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

selectPreviousKeyView:

This action method searches for a candidate previous key view and, if it finds one, invokes makeFirstResponder: to establish it as the first responder.

- (void)selectPreviousKeyView:(id)sender
Parameters
sender

The message’s sender.

Discussion

The candidate is one of the following (searched for in this order):

  • The current first responder’s previous valid key view, as returned by the previousValidKeyView method of NSView

  • The object designated as the window’s initial first responder (using setInitialFirstResponder:) if it returns YES to an acceptsFirstResponder message

  • Otherwise, the initial first responder’s previous valid key view, which may end up being nil

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

sendEvent:

This action method dispatches mouse and keyboard events sent to the window by the NSApplication object.

- (void)sendEvent:(NSEvent *)event
Parameters
event

The mouse or keyboard event to process.

Discussion

Never invoke this method directly. A right mouse-down event in a window of an inactive application is not delivered to the corresponding NSWindow object. It is instead delivered to the NSApplication object through a sendEvent: message with a window number of 0.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setAcceptsMouseMovedEvents:

Specifies whether the window is to accept mouse-moved events.

- (void)setAcceptsMouseMovedEvents:(BOOL)acceptMouseMovedEvents
Parameters
acceptMouseMovedEvents

YES to have the window accept mouse-moved events (and to distribute them to its responders); NO to not accept such events.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setAllowsConcurrentViewDrawing:

Specifies whether the window allows its views to be drawn concurrently.

- (void)setAllowsConcurrentViewDrawing:(BOOL)flag
Parameters
flag

If YES, the window allows its views to be drawn concurrently; if NO, it does not.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
NSWindow.h

setAllowsToolTipsWhenApplicationIsInactive:

Specifies whether the window can display tooltips even when the application is in the background.

- (void)setAllowsToolTipsWhenApplicationIsInactive:(BOOL)allowTooltipsWhenAppInactive
Parameters
allowTooltipsWhenAppInactive

YES to have the window display tooltips even when its application is inactive; NO to suppress tooltip display when inactive.

Discussion

The message does not take effect until the window changes to an active state.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

setAlphaValue:

Applies a given alpha value to the entire window.

- (void)setAlphaValue:(CGFloat)windowAlpha
Parameters
windowAlpha

The alpha value to apply.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setAnchorAttribute:forOrientation:

Sets which part of the window stays stationary during constrain based layout.

- (void)setAnchorAttribute:(NSLayoutAttribute)attr forOrientation:(NSLayoutConstraintOrientation)orientation
Parameters
attr

The layout attribute. The possible values are specified in NSLayoutAttribute.

orientation

The window drag orientation. The possible values are specified in NSLayoutConstraintOrientation.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

setAnimationBehavior:

Sets the window’s automatic animation behavior.

- (void)setAnimationBehavior:(NSWindowAnimationBehavior)newAnimationBehavior
Parameters
newAnimationBehavior

The new animation behavior for the window. See “NSWindowAnimationBehavior” for the possible values.

Discussion

This controls the automatic window animation behavior used when a window is sent an orderFront: or orderOut: message.

By default, a window’s animation behavior is set to NSWindowAnimationBehaviorDefault, which causes AppKit to determine the style of animation to use automatically based on its inference of a window’s “type” from various window properties.

A window’s animation behavior can be set to NSWindowAnimationBehaviorNone to disable AppKit’s automatic animations for the window, which may be useful if that animation interferes with an animation that your application implements.

The animation behavior can also be set to one of the other non-default “NSWindowAnimationBehavior” values to override AppKit's automatic inference of appropriate animation behavior based on the window's apparent type, although this is not recommended.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindow.h

setAspectRatio:

Sets the window’s aspect ratio, which constrains the size of its frame rectangle to integral multiples of this ratio when the user resizes it.

- (void)setAspectRatio:(NSSize)aspectRatio
Parameters
aspectRatio

The aspect ratio to be maintained during resizing actions.

Discussion

An NSWindow object’s aspect ratio and its resize increments are mutually exclusive attributes. In fact, setting one attribute cancels the setting of the other. For example, to cancel an established aspect ratio setting for an NSWindow object, you send it a setResizeIncrements: message with the width and height set to 1.0:

[myWindow setResizeIncrements:NSMakeSize(1.0,1.0)];

The setContentAspectRatio: method takes precedence over this method.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setAutodisplay:

Specifies whether the window is to automatically display the views that are marked as needing it.

- (void)setAutodisplay:(BOOL)autodisplay
Parameters
autodisplay

If YES, the window will automatically display views that need to be displayed; if NO, it will not.

Discussion

If autodisplay is NO, the window or its views must be explicitly displayed.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setAutorecalculatesContentBorderThickness:forEdge:

Specifies whether the window calculates the thickness of a given border automatically.

- (void)setAutorecalculatesContentBorderThickness:(BOOL)flag forEdge:(NSRectEdge)edge
Parameters
autorecalculateContentBorderThickness

If YES, the window calculates the thickness of the edge automatically; if NO, it does not.

edge

The border to set auto-recalculation on or off:

Special Considerations

Turning off a border’s auto-recalculation status sets its border thickness to 0.0.

In a nontextured window calling setAutorecalculatesContentBorderThickness:forEdge: passing NSMaxYEdge will raise an exception (in a nontextured window, it’s only valid to set the content border thickness of the bottom edge). It is only valid to set the content border thickness of the top edge in a textured window.

Typically, if you call setContentBorderThickness:forEdge:, you should also call setAutorecalculatesContentBorderThickness:NO forEdge:.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

setAutorecalculatesKeyViewLoop:

Specifies whether to recalculate the key view loop automatically when views are added or removed.

- (void)setAutorecalculatesKeyViewLoop:(BOOL)autorecalculateKeyViewLoop
Parameters
autorecalculateKeyViewLoop

If YES,the window recalculates the key view loop automatically; if NO, it does not.

Discussion

If autorecalculateKeyViewLoop is NO, the client code must update the key view loop manually or call recalculateKeyViewLoop to have the window recalculate it.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSWindow.h

setBackgroundColor:

Sets the window’s background color to the given color.

- (void)setBackgroundColor:(NSColor *)color
Parameters
color

Color to set as the window’s background color.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setBackingType:

Sets the window’s backing store type to a given type.

- (void)setBackingType:(NSBackingStoreType)backingType
Parameters
backingType

The backing store type to set.

Discussion

The valid backing store types are described in “Constants.”

This method can be used only to switch a buffered window to retained or vice versa; you can’t change the backing type to or from nonretained after initializing an NSWindow object (an error is generated if you attempt to do so).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setCanBecomeVisibleWithoutLogin:

Specifies whether the window can be displayed at the login window.

- (void)setCanBecomeVisibleWithoutLogin:(BOOL)flag
Parameters
flag

YES to allow the window to be displayed at the login window; NO to prevent this behavior.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
NSWindow.h

setCanHide:

Specifies whether the window can be hidden when its application becomes hidden (during execution of the NSApplication hide: method).

- (void)setCanHide:(BOOL)canHide
Parameters
canHide

If YES, the window can be hidden when its application becomes hidden; if NO, it cannot.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

setCollectionBehavior:

Specifies the window’s behavior in window collections.

- (void)setCollectionBehavior:(NSWindowCollectionBehavior)behavior
Parameters
collectionBehavior

The collection behavior identifier to set.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

setColorSpace:

Sets the window’s color space.

- (void)setColorSpace:(NSColorSpace *)colorSpace
Parameters
colorSpace

The color space to set.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

setContentAspectRatio:

Sets the aspect ratio (height in relation to width) of the window’s content view, constraining the dimensions of its content rectangle to integral multiples of that ratio when the user resizes it.

- (void)setContentAspectRatio:(NSSize)contentAspectRatio
Parameters
contentAspectRatio

The aspect ratio of the window’s content view.

Discussion

You can set a window’s content view to any size programmatically, regardless of its aspect ratio. This method takes precedence over setAspectRatio:.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

setContentBorderThickness:forEdge:

Specifies the thickness of a given border of the window.

- (void)setContentBorderThickness:(CGFloat)thickness forEdge:(NSRectEdge)edge
Parameters
borderThickness

The thickness for edge, in points.

edge

The border whose thickness to set:

Discussion

In a nontextured window calling setContentBorderThickness:forEdge: passing NSMaxYEdge will raise an exception (in a nontextured window, it’s only valid to set the content border thickness of the bottom edge). It is only valid to set the content border thickness of the top edge in a textured window.

Typically, if you call setContentBorderThickness:forEdge:, you should also call setAutorecalculatesContentBorderThickness:NO forEdge:.

The contentBorder does not include the titlebar or toolbar, so a textured window that just wants the gradient in the titlebar and toolbar should have a contentBorderThickness of 0 for NSMaxYEdge.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
NSWindow.h

setContentMaxSize:

Sets the maximum size of the window’s content view in the window’s base coordinate system.

- (void)setContentMaxSize:(NSSize)contentMaxSize
Parameters
contentMaxSize

The maximum size of the window’s content view in the window’s base coordinate system.

Discussion

The maximum size constraint is enforced for resizing by the user as well as for the setContentSize: method and the setFrame... methods other than setFrame:display: and setFrame:display:animate:. This method takes precedence over setMaxSize:.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

setContentMinSize:

Sets the minimum size of the window’s content view in the window’s base coordinate system.

- (void)setContentMinSize:(NSSize)contentMinSize
Parameters
contentMinSize

The minimum size of the window’s content view in the window’s base coordinate system.

Discussion

The minimum size constraint is enforced for resizing by the user as well as for the setContentSize: method and the setFrame... methods other than setFrame:display: and setFrame:display:animate:. This method takes precedence over setMinSize:.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

setContentResizeIncrements:

Restricts the user’s ability to resize the window so the width and height of its content view change by multiples of width and height increments.

- (void)setContentResizeIncrements:(NSSize)contentResizeIncrements
Parameters
contentResizeIncrements

The content-view resizing increments to set.

Discussion

As the user resizes the window, the size of its content view changes by integral multiples of contentResizeIncrements.width and contentResizeIncrements.height. However, you can set a window’s size to any width and height programmatically. This method takes precedence over setResizeIncrements:.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSWindow.h

setContentSize:

Sets the size of the window’s content view to a given size, which is expressed in the window’s base coordinate system.

- (void)setContentSize:(NSSize)size
Parameters
size

The new size of the window’s content view in the window’s base coordinate system.

Discussion

This size in turn alters the size of the NSWindow object itself. Note that the window server limits window sizes to 10,000; if necessary, be sure to limit aSize relative to the frame rectangle.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

setContentView:

Makes a given view the window’s content view.

- (void)setContentView:(NSView *)view
Parameters
view

View that is to become the window’s content view.

Discussion

The window retains the new content view and owns it thereafter. The view object is resized to fit precisely within the content area of the window. You can modify the content view’s coordinate system through its bounds rectangle, but can’t alter its frame rectangle (that is, its size or location) directly.

This method causes the old content view to be released; if you plan to reuse it, be sure to retain it before sending this message and to release it as appropriate when adding it to another NSWindow object or NSView.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setDefaultButtonCell:

Makes the key equivalent of button cell the Return (or Enter) key, so when the user presses Return that button performs as if clicked.

- (void)setDefaultButtonCell:(NSButtonCell *)defaultButtonCell
Parameters
defaultButtonCell

The button cell to perform as if clicked when the window receives a Return (or Enter) key event.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setDelegate:

Sets the window’s delegate to a given object or removes an existing delegate.

- (void)setDelegate:(id < NSWindowDelegate >)delegate
Parameters
delegate

The delegate for the window. Pass nil to remove an existing delegate.

Discussion

An NSWindow object’s delegate is inserted in the responder chain after the window itself and is informed of various actions by the window through delegation messages.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setDepthLimit:

Sets the depth limit of the window to a given limit.

- (void)setDepthLimit:(NSWindowDepth)depthLimit
Parameters
depthLimit

The depth limit to set.

Discussion

The NSBestDepth function provides the best depth limit based on a set of parameters.

Passing a value of 0 for depthLimit sets the depth limit to the window’s default depth limit. A depth limit of 0 can be useful for reverting an NSWindow object to its initial depth.

On OS X v10.6 and later, you can pass one of the explicit bit depths defined in “Explicit Window Depth Limits”NSWindowDepthTwentyfourBitRGB is the default.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setDisplaysWhenScreenProfileChanges:

Specifies whether the window context should be updated when the screen profile changes.

- (void)setDisplaysWhenScreenProfileChanges:(BOOL)displaysWhenScreenProfileChanges
Parameters
displaysWhenScreenProfileChanges
  • YES specifies that the window context should be changed in these situations:

    • A majority of the window is moved to a different screen whose profile is different than the previous screen.

    • The ColorSync profile of the current screen changes.

  • NO specifies that the screen profile information for the window context doesn’t change.

Discussion

After the window context is updated, the window is told to display itself. If you need to update offscreen caches for the window, you should register to receive the NSWindowDidChangeScreenProfileNotification notification.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
NSWindow.h

setDocumentEdited:

Specifies whether the window’s document has been edited.

- (void)setDocumentEdited:(BOOL)documentEdited
Parameters
documentEdited

If YES, the window’s document is marked as having been edited; if NO, it is marked as not having been edited.

Discussion

You should send setDocumentEdited:YES to an NSWindow object every time the window’s document changes in such a way that it needs to be saved. Conversely, when the document is saved, you should send setDocumentEdited:NO. Then, before closing the window you can use isDocumentEdited to determine whether to allow the user a chance to save the document.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

setDynamicDepthLimit:

Sets whether the window changes its depth to match the depth of the screen it’s on, or the depth of the deepest screen when it spans multiple screens.

- (void)setDynamicDepthLimit:(BOOL)dynamicDepthLimit
Parameters
dynamicDepthLimit

If YES, the window has a dynamic depth limit; if NO, it does not.

Discussion

When dynamicDepthLimit is NO, the window uses either its preset depth limit or the default depth limit. A different, and non-dynamic, depth limit can be set with the setDepthLimit: method.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setExcludedFromWindowsMenu:

Specifies whether the window’s title is omitted from the application’s Windows menu.

- (void)setExcludedFromWindowsMenu:(BOOL)excludedFromWindowsMenu
Parameters
excludedFromWindowsMenu

If YES, the window will be omitted from the application’s Windows menu; if NO, it will not be omitted.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setFrame:display:

Sets the origin and size of the window’s frame rectangle according to a given frame rectangle, thereby setting its position and size onscreen.

- (void)setFrame:(NSRect)windowFrame display:(BOOL)displayViews
Parameters
windowFrame

The frame rectangle for the window, including the title bar.

displayViews

Specifies whether the window redraws the views that need to be displayed. When YES the window sends a displayIfNeeded message down its view hierarchy, thus redrawing all views.

Discussion

Note that the window server limits window position coordinates to ±16,000 and sizes to 10,000.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setFrame:display:animate:

Sets the origin and size of the window’s frame rectangle, with optional animation, according to a given frame rectangle, thereby setting its position and size onscreen.

- (void)setFrame:(NSRect)windowFrame display:(BOOL)displayViews animate:(BOOL)performAnimation
Parameters
windowFrame

The frame rectangle for the window, including the title bar.

displayViews

Specifies whether the window redraws the views that need to be displayed. When YES the window sends a displayIfNeeded message down its view hierarchy, thus redrawing all views.

performAnimation

Specifies whether the window performs a smooth resize. YES to perform the animation, whose duration is specified by animationResizeTime:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setFrameAutosaveName:

Sets the name used to automatically save the window’s frame rectangle in the defaults system to a given name.

- (BOOL)setFrameAutosaveName:(NSString *)frameName
Parameters
frameName

The name under which the frame is to be saved.

Return Value

YES when the frame name is set successfully; NO when frameName is being used as an autosave name by another NSWindow object in the application (in which case the window’s old name remains in effect).

Discussion

If frameName isn’t the empty string (@""), the window’s frame is saved as a user default (as described in saveFrameUsingName:) each time the frame changes.

When the window has an autosave name, its frame data is written whenever the frame rectangle changes.

If there is a frame rectangle previously stored for frameName in the user defaults, the window’s frame is set to this frame rectangle. That is, when you call this method with a previously used frameName, the window picks up the previously saved setting. For example, if you call setFrameAutosaveName: for a window that is already onscreen, this method could cause the window to move to a different screen location. For this reason, it is generally better to call this method before the window is visible on screen.

Keep in mind that a window controller may change the window’s position when it displays it if window cascading is turned on. To preclude the window controller from changing a window’s position from the one saved in the defaults system, you must send setShouldCascadeWindows:NO to the window controller.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

setFrameFromString:

Sets the window’s frame rectangle from a given string representation.

- (void)setFrameFromString:(NSString *)frameString
Parameters
frameString

A string representation of a frame rectangle, previously creating using stringWithSavedFrame.

Discussion

If the window is not resizable, this method will not resize the window. The frame is constrained according to the window’s minimum and maximum size settings. This method causes a windowWillResize:toSize: message to be sent to the delegate.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setFrameOrigin:

Positions the bottom-left corner of the window’s frame rectangle at a given point in screen coordinates.

- (void)setFrameOrigin:(NSPoint)point
Parameters
point

The new position of the window’s bottom-left corner in screen coordinates.

Discussion

Note that the window server limits window position coordinates to ±16,000.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setFrameTopLeftPoint:

Positions the top-left corner of the window’s frame rectangle at a given point in screen coordinates.

- (void)setFrameTopLeftPoint:(NSPoint)point
Parameters
point

The new position of the window’s top-left corner in screen coordinates.

Discussion

Note that the window server limits window position coordinates to ±16,000; if necessary, adjust aPoint relative to the window’s lower-left corner to account for this limit.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

setFrameUsingName:

Sets the window’s frame rectangle by reading the rectangle data stored under a given name from the defaults system.

- (BOOL)setFrameUsingName:(NSString *)frameName
Parameters
frameName

The name of the frame to read.

Return Value

YES when frameName is read and the frame is set successfully; otherwise, NO.

Discussion

The frame is constrained according to the window’s minimum and maximum size settings. This method causes a windowWillResize:toSize: message to be sent to the delegate.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setFrameUsingName:force:

Sets the window’s frame rectangle by reading the rectangle data stored under a given name from the defaults system. Can operate on non-resizable windows.

- (BOOL)setFrameUsingName:(NSString *)frameName force:(BOOL)force
Parameters
frameName

The name of the frame to read.

force

YES to use setFrameUsingName: on a non-resizable window; NO to fail on a non-resizable window.

Return Value

YES when frameName is read and the frame is set successfully; otherwise,NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setHasShadow:

Specifies whether the window has a shadow.

- (void)setHasShadow:(BOOL)hasShadow
Parameters
hasShadow

If YES, the window has a shadow; if NO, it does not.

Discussion

If the shadow setting changes, the window shadow is invalidated, forcing the window shadow to be recomputed.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

setHidesOnDeactivate:

Specifies whether the window is removed from the screen when the application is inactive.

- (void)setHidesOnDeactivate:(BOOL)hideOnDeactivate
Parameters
hideOnDeactivate
  • YES specifies that the window is to be hidden (taken out of the screen list) when the application stops being the active application

  • NO specifies that the window is to remain onscreen when the application becomes inactive.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setIgnoresMouseEvents:

Specifies whether the window is transparent to mouse clicks and other mouse events, allowing overlay windows.

- (void)setIgnoresMouseEvents:(BOOL)ignoreMouseEvents
Parameters
ignoreMouseEvents

If YES, the window will ignore mouse events; if NO, it will not.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
NSWindow.h

setInitialFirstResponder:

Sets a given view as the one that’s made first responder (also called the key view) the first time the window is placed onscreen.

- (void)setInitialFirstResponder:(NSView *)view
Parameters
view

The view to make first responder the first time the window is placed onscreen.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setLevel:

Sets the window’s window level to a given level.

- (void)setLevel:(NSInteger)windowLevel
Parameters
windowLevel

The window level to set.

Discussion

Some useful predefined values, ordered from lowest to highest, are described in “Window Levels.”

Each level in the list groups windows within it in front of those in all preceding groups. Floating windows, for example, appear in front of all normal-level windows. When a window enters a new level, it’s ordered in front of all its peers in that level.

The constant NSTornOffMenuWindowLevel is preferable to its synonym, NSSubmenuWindowLevel.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setMaxSize:

Sets the maximum size to which the window’s frame (including its title bar) can be sized.

- (void)setMaxSize:(NSSize)maxFrameSize
Parameters
maxFrameSize

The maximum size of the window’s frame.

Discussion

The maximum size constraint is enforced for resizing by the user as well as for the setFrame... methods other than setFrame:display: and setFrame:display:animate:. Note that the window server limits window sizes to 10,000.

The default maximum size of a window is {FLT_MAX, FLT_MAX} (FLT_MAX is defined in /usr/include/float.h). Once the maximum size of a window has been set, there is no way to reset it other than specifying this default maximum size.

The setContentMaxSize: method takes precedence over this method.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

setMiniwindowImage:

Sets the window’s custom minimized window image to a given image.

- (void)setMiniwindowImage:(NSImage *)miniwindowImage
Parameters
miniwindowImage

Image to set as the window’s minimized window image.

Discussion

When the user minimizes the window, the Dock displays miniwindowImage in the corresponding Dock tile, scaling it as needed to fit in the tile. If you do not specify a custom image using this method, the Dock creates one for you automatically.

You can also call this method as needed to change the minimized window image. Typically, you would specify a custom image immediately prior to a window being minimized—when the system posts an NSWindowWillMiniaturizeNotification. You can call this method while the window is minimized to update the current image in the Dock. However, this method is not recommended for creating complex animations in the Dock.

Support for custom images is disabled by default. To enable support, set the AppleDockIconEnabled key to YES when first registering your application’s user defaults. You must set this key prior to calling the init method of NSApplication, which reads the current value of the key.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setMiniwindowTitle:

Sets the title of the window’s miniaturized counterpart to a given string and redisplays it.

- (void)setMiniwindowTitle:(NSString *)miniwindowTitle
Parameters
miniwindowTitle

The string to set as the title of the minimized window.

Discussion

A minimized window’s title normally reflects that of its full-size counterpart, abbreviated to fit if necessary. Although this method allows you to set the minimized window’s title explicitly, changing the full-size NSWindow object’s title (through setTitle: or setTitleWithRepresentedFilename:) automatically changes the minimized window’s title as well.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setMinSize:

Sets the minimum size to which the window’s frame (including its title bar) can be sized to aSize.

- (void)setMinSize:(NSSize)minFrameSize
Parameters
minFrameSize

The minimum size of the window’s frame.

Discussion

The minimum size constraint is enforced for resizing by the user as well as for the setFrame... methods other than setFrame:display: and setFrame:display:animate:.

The setContentMinSize: method takes precedence over this method.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setMovable:

Specifies whether the window can be dragged by clicking in its title bar or background.

- (void)setMovable:(BOOL)flag
Parameters
flag

If YES, dragging is enabled; if NO, it is disabled.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

setMovableByWindowBackground:

Sets whether the window is movable by clicking and dragging anywhere in its background.

- (void)setMovableByWindowBackground:(BOOL)movableByWindowBackground
Parameters
movableByWindowBackground

YES to specify that the window is movable by background, NO to specify that the window is not movable by background.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSWindow.h

setOneShot:

Sets whether the window device that the window manages should be freed when it’s removed from the screen list.

- (void)setOneShot:(BOOL)oneShot
Parameters
oneShot

YES to free the window’s window device when it’s removed from the screen list (hidden) and to create another one when it’s returned to the screen; NO to reuse the window device.

Discussion

Freeing the window device when it’s removed from the screen list can result in memory savings and performance improvement for NSWindow objects that don’t take long to display. It’s particularly appropriate for NSWindow objects the user might use once or twice but not display continually.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setOpaque:

Specifies whether the window is opaque.

- (void)setOpaque:(BOOL)opaque
Parameters
opaque

If YES, the window is opaque; if NO, it is not.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

setParentWindow:

Adds the window as a child of a given window. For use by subclasses when setting the parent window in the window.

- (void)setParentWindow:(NSWindow *)parentWindow
Parameters
parentWindow

The window to be a child of the given window.

Discussion

This method should be called from a subclass when it is overridden by a subclass’s implementation. It should not be called otherwise.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
NSWindow.h

setPreferredBackingLocation:

Specifies the preferred location for the window’s backing store.

- (void)setPreferredBackingLocation:(NSWindowBackingLocation)backingLocation
Parameters
preferredBackingLocation

The preferred location for the window’s backing store. See “NSWindowBackingLocation” for possible values.

Discussion

Use only when optimizing for performance.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
NSWindow.h

setPreservesContentDuringLiveResize:

Specifies whether the window tries to optimize live resize operations by preserving the content of views that have not changed.

- (void)setPreservesContentDuringLiveResize:(BOOL)preservesContentDuringLiveResize
Parameters
preservesContentDuringLiveResize

YES turns on live-resize optimization; NO turns it off for the window and all of its contained views.

Discussion

By default, live-resize optimization is turned on.

You might consider disabling this optimization for the window if none of the window’s contained views can take advantage of it. Disabling the optimization for the window prevents it from checking each view to see if the optimization is supported.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSWindow.h

setPreventsApplicationTerminationWhenModal:

Specifies whether the window prevents application termination when modal.

- (void)setPreventsApplicationTerminationWhenModal:(BOOL)flag
Parameters
flag

If YES, the window will prevent application termination when modal; if NO, it will not.

Discussion

Normally, application termination is prevented when a modal window or sheet is open, without consulting the application delegate. Some windows may wish not to prevent termination, however. Calling this method with an argument of NO overrides the default behavior and allows termination to proceed even if the window is open, either through the sudden termination path if enabled, or after consulting the application delegate.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

setReleasedWhenClosed:

Specifies whether the window is released when it receives the close message.

- (void)setReleasedWhenClosed:(BOOL)releasedWhenClosed
Parameters
releasedWhenClosed

YES to specify that the window is to be hidden and released when it receives a close message; NO to specify that the window is only hidden, not released.

Discussion

Another strategy for releasing an NSWindow object is to have its delegate autorelease it on receiving a windowShouldClose: message.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setRepresentedFilename:

Sets the pathname of the file the window represents.

- (void)setRepresentedFilename:(NSString *)filePath
Parameters
filePath

The path to the file to set as the window’s represented file.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setRepresentedURL:

Specifies the URL of the file the window represents.

- (void)setRepresentedURL:(NSURL *)url
Parameters
representedURL

The URL of the file the window is to represent.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

setResizeIncrements:

Restricts the user’s ability to resize the window so the width and height change by multiples of width and height increments.

- (void)setResizeIncrements:(NSSize)resizeIncrements
Parameters
resizeIncrements

The resizing increments to set.

Discussion

As the user resizes the window, its size changes by multiples of increments.width and increments.height, which should be whole numbers, 1.0 or greater. Whatever the current resizing increments, you can set an NSWindow object’s size to any height and width programmatically.

Resize increments and aspect ratio are mutually exclusive attributes. For more information, see setAspectRatio:.

The setContentResizeIncrements: method takes precedence over this method.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setRestorable:

Specifies whether the window configuration is preserved between application launches.

- (void)setRestorable:(BOOL)flag
Parameters
flag

Specify YES if you want the window to be preserved or NO if you do not want it preserved.

Discussion

Windows should be preserved between launch cycles to maintain interface continuity for the user. During subsequent launch cycles, the system tries to recreate the window and restore its configuration to the preserved state. Configuration data is updated as needed and saved automatically by the system.

If you enable preservation for a given window, you should also specify a restoration class for the window using the setRestorationClass: method.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindowRestoration.h

setRestorationClass:

Specifies the class to use to acquire a matching window object during subsequent launches.

- (void)setRestorationClass:(Class < NSWindowRestoration >)restorationClass
Parameters
restorationClass

A class object that conforms to the NSWindowRestoration protocol. AppKit uses this object to handle the recreation of the window object later.

Discussion

The restoration class of a window is responsible for recreating not just the window but any other objects needed to manage the window. This almost always involves creating a window controller and for multi-window document applications also involves creating a document object. Therefore, the restoration class must be able to create (or find existing instances of) all of these objects at launch time in your application.

If you mark your windows as restorable, you must associate a restoration class with them. For multi-window document applications, AppKit associates the NSDocumentController class with any document windows by default. That class recreates the preserved document objects, which in turn recreate the corresponding window controller and window objects. For other types of windows, you must set the restoration class explicitly.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSWindowRestoration.h

setSharingType:

Specifies the level of access other processes have to the window’s content.

- (void)setSharingType:(NSWindowSharingType)type
Parameters
sharingType

The sharing level of the window’s content. See “NSWindowSharingType” for possible values.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

setShowsResizeIndicator:

Specifies whether the window’s resize indicator is visible

- (void)setShowsResizeIndicator:(BOOL)showResizeIndicator
Parameters
showResizeIndicator

Specifies the resize indicator state. YES to show it, NO to hide it.

Discussion

This method does not affect whether the window is resizable.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setShowsToolbarButton:

Specifies whether the window shows the toolbar control button.

- (void)setShowsToolbarButton:(BOOL)showsToolbarButton
Parameters
showsToolbarButton

YES to display the toolbar control button; NO to hide the button.

Discussion

If the window does not have a toolbar, this method has no effect.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSWindow.h

setStyleMask:

Sets the window’s style mask to the given value.

- (void)setStyleMask:(NSUInteger)styleMask
Parameters
styleMask

The new style mask value. See “Window Style Masks” for possible values.

Discussion

The valid style mask values are the same values acceptable for use in initWithContentRect:styleMask:backing:defer:. Some style mask changes cause the view hierarchy to be rebuilt.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSWindow.h

setTitle:

Sets the string that appears in the window’s title bar (if it has one) to a given string and displays the title.

- (void)setTitle:(NSString *)title
Parameters
title

The string to set as the window’s title.

Discussion

Also sets the title of the window’s miniaturized window.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setTitleWithRepresentedFilename:

Sets a given path as the window’s title, formatting it as a file-system path, and records this path as the window’s associated filename using setRepresentedFilename:.

- (void)setTitleWithRepresentedFilename:(NSString *)filePath
Parameters
filePath

The file path to set as the window’s title.

Discussion

The filename—not the pathname—is displayed in the window’s title bar.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setToolbar:

Sets the window’s toolbar.

- (void)setToolbar:(NSToolbar *)toolbar
Parameters
toolbar

The toolbar for the window.

Discussion

See the NSToolbar class description for additional information.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSWindow.h

setViewsNeedDisplay:

Specifies whether the window’s views need to be displayed..

- (void)setViewsNeedDisplay:(BOOL)viewsNeedDisplay
Parameters
viewsNeedDisplay

If YES, the window’s views are set to need to be displayed; if NO, they are not.

Discussion

You should rarely need to invoke this method; the NSView method setNeedsDisplay: and similar methods invoke it automatically.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

setWindowController:

Sets the window’s window controller.

- (void)setWindowController:(NSWindowController *)windowController
Parameters
windowController

Window controller to set.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

sharingType

Indicates the level of access other processes have to the window’s content.

- (NSWindowSharingType)sharingType
Return Value

The sharing level of the window’s content. See “NSWindowSharingType” for possible values.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSWindow.h

sheetParent

Returns the window to which the sheet is attached.

- (NSWindow *)sheetParent
Return Value

The window object to which the sheet is attached or nil if the receiver is not a sheet or has no sheet parent.

Discussion

This method returns the window object to which the sheet is logically attached, regardless of appearance. The parent window–sheet relationship begins with the beginning of the sheet (for example, through beginSheet:completionHandler:) and ends with the sheet’s dismissal (for example, through endSheet:).

Availability
  • Available in OS X v10.9 and later.
Declared In
NSWindow.h

sheets

Returns an array of the sheets currently attached to the window.

- (NSArray *)sheets
Return Value

An ordered array that contains—in top-to-bottom order—the presented sheets that are attached to the window, followed by queued sheets, in the order they were queued. The array doesn’t include nested sheets or subsheets.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSWindow.h

showsResizeIndicator

Returns a Boolean value that indicates whether the window’s resize indicator is visible.

- (BOOL)showsResizeIndicator
Return Value

YES when the window’s resize indicator is visible; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

showsToolbarButton

Indicates whether the toolbar control button is currently displayed.

- (BOOL)showsToolbarButton
Return Value

YES if the standard toolbar button is currently displayed; otherwise, NO.

Discussion

When clicked, the toolbar control button shows or hides a window’s toolbar. The toolbar control button appears in a window’s title bar.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSWindow.h

standardWindowButton:

Returns the window button of a given window button kind in the window’s view hierarchy.

- (NSButton *)standardWindowButton:(NSWindowButton)windowButtonKind
Parameters
windowButtonKind

The kind of standard window button to return.

Return Value

Window button in the window’s view hierarchy of the kind identified by windowButtonKind; nil when such button is not in the window’s view hierarchy.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSWindow.h

stringWithSavedFrame

Returns a string representation of the window’s frame rectangle.

- (NSString *)stringWithSavedFrame
Return Value

A string representation of the window’s frame rectangle in a format that can be used with a later setFrameFromString: message.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

styleMask

Returns the window’s style mask, indicating what kinds of control items it displays.

- (NSUInteger)styleMask
Return Value

The window’s style mask.

Discussion

See the information about the style mask in “Window Style Masks.”

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

title

Returns either the string that appears in the title bar of the window, or the path to the represented file.

- (NSString *)title
Return Value

The window’s title or the path to the represented file.

Discussion

If the title has been set using setTitleWithRepresentedFilename:, this method returns the file’s path.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

toggleFullScreen:

Taken the window into or out of fullscreen mode,

- (void)toggleFullScreen:(id)sender
Parameters
sender

The object that sent the message.

Discussion

If an application supports fullscreen, it should add a menu item to the View menu with toggleFullScreen: as the action, and nil as the target.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSWindow.h

toggleToolbarShown:

The action method for the “Hide Toolbar” menu item (which alternates with “Show Toolbar”).

- (void)toggleToolbarShown:(id)sender
Parameters
sender

The message’s sender.

Discussion

See the NSToolbar class description for additional information.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

toolbar

Returns the window’s toolbar.

- (NSToolbar *)toolbar
Return Value

The window’s toolbar.

Discussion

See the NSToolbar class description for additional information.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

tryToPerform:with:

Dispatches action messages with a given argument.

- (BOOL)tryToPerform:(SEL)selector with:(id)object
Parameters
selector

The selector to attempt to execute.

object

The message’s argument.

Return Value

YES when the window or its delegate perform selector with object; otherwise, NO.

Discussion

The window tries to perform the method selector using its inherited NSResponder method tryToPerform:with:. If the window doesn’t perform selector, the delegate is given the opportunity to perform it using its inherited NSObject method performSelector:withObject:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

unregisterDraggedTypes

Unregisters the window as a possible destination for dragging operations.

- (void)unregisterDraggedTypes
Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

update

Updates the window.

- (void)update
Discussion

The NSWindow implementation of this method does nothing more than post an NSWindowDidUpdateNotification notification to the default notification center. A subclass can override this method to perform specialized operations, but it should send an update message to super just before returning. For example, the NSMenu class implements this method to disable and enable menu commands.

An NSWindow object is automatically sent an update message on every pass through the event loop and before it’s displayed onscreen. You can manually cause an update message to be sent to all visible NSWindow objects through the NSApplication updateWindows method.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

updateConstraintsIfNeeded

Updates the constraints based on changes to views in the window since the last layout.

- (void)updateConstraintsIfNeeded
Discussion

Whenever a new layout pass is triggered for a window, the system invokes this method to ensure that any constraints for views in the window are updated with information from the current view hierarchy and its constraints. This method is called automatically by the system, but may be invoked manually if you need to examine the most up to date constraints.

Subclasses should not override this method.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

useOptimizedDrawing:

Specifies whether the window is to optimize focusing and drawing when displaying its views.

- (void)useOptimizedDrawing:(BOOL)optimizedDrawing
Parameters
optimizedDrawing

If YES, the window will optimize focusing and drawing for its views; if NO, it will not, in which case, the window does not preserve the Z-ordering of overlapping views when an object explicitly sends lockFocus to a view and draws directly to it, instead of using the AppKit standard display mechanism.

Discussion

The optimizations may prevent sibling subviews from being displayed in the correct order—which matters only if the subviews overlap. You should always set optimizedDrawing to YES when there are no overlapping subviews within the window. The default is NO.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

userSpaceScaleFactor

Returns the scale factor applied to the window. (Deprecated. Use convertRectToBacking: and backingScaleFactor instead.)

- (CGFloat)userSpaceScaleFactor
Return Value

The scale factor applied to the window.

Discussion

Clients can multiply view coordinates by the returned scale factor to get a set of new coordinates that are scaled to the resolution of the target screen. For example, if the scale factor is 1.25 and the view frame size is 80 x 80, the actual size of the view frame is 100 x 100 pixels on the target screen.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSWindow.h

validRequestorForSendType:returnType:

Searches for an object that responds to a Services request.

- (id)validRequestorForSendType:(NSString *)sendType returnType:(NSString *)returnType
Parameters
sendType

The input type of the Services request.

returnType

The return type of the Services request.

Return Value

The object that responds to the services request; nil when none is found.

Discussion

Messages to perform this method are initiated by the Services menu. It’s part of the mechanism that passes validRequestorForSendType:returnType: messages up the responder chain.

This method works by forwarding the message to the window’s delegate if it responds (and provided it isn’t an NSResponder object with its own next responder). If the delegate doesn’t respond to the message or returns nil when sent it, this method forwards the message to the NSApplication object. If the NSApplication object returns nil, this method also returns nil. Otherwise this method returns the object returned by the delegate or the NSApplication object.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

viewsNeedDisplay

Indicates whether any of the window’s views need to be displayed.

- (BOOL)viewsNeedDisplay
Return Value

YES when any of the window’s views need to be displayed; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

visualizeConstraints:

Displays a visual representation of the supplied constraints in the window.

- (void)visualizeConstraints:(NSArray *)constraints
Parameters
constraints

The constraints to visualize. All constraints must be held by views in the window.

Discussion

The constraints to visualize are typically discovered by identifying a view whose layout is unexpected and then calling constraintsAffectingLayoutForOrientation: on that view.

This method should only be used for debugging constraint-based layout. No application should ship with calls to this method as part of its operation.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

windowController

Returns the window’s window controller.

- (id)windowController
Return Value

The window’s window controller.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

windowNumber

Provides the window number of the window’s window device.

- (NSInteger)windowNumber
Return Value

The window number of the window’s window device.

Discussion

Each window device in an application is given a unique window number—note that this isn’t the same as the global window number assigned by the window server. This number can be used to identify the window device with the orderWindow:relativeTo: method and in the Application Kit function NSWindowList. .

If the window doesn’t have a window device, the value returned will be equal to or less than 0.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSWindow.h

windowRef

Returns the Carbon WindowRef associated with the window, creating one if necessary.

- (void *)windowRef
Discussion

This method can be used to create a WindowRef for a window containing a Carbon control. Subsequent calls to this method return the existing WindowRef. You use a WindowRef to create a Carbon window reference for a Cocoa window; this assists the integration of Carbon and Cocoa code and objects.

For more information see MacWindows.h. For more information on Carbon-Cocoa integration, see Carbon-Cocoa Integration Guide.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSWindow.h

worksWhenModal

Indicates whether the window is able to receive keyboard and mouse events even when some other window is being run modally.

- (BOOL)worksWhenModal
Return Value

YES if the window is able to receive keyboard and mouse events even when some other window is being run modally; otherwise, NO.

Discussion

The NSWindow implementation of this method returns NO. Only subclasses of NSPanel should override this default.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSWindow.h

zoom:

This action method toggles the size and location of the window between its standard state (provided by the application as the “best” size to display the window’s data) and its user state (a new size and location the user may have set by moving or resizing the window).

- (void)zoom:(id)sender
Parameters
sender

The object sending the message.

Discussion

For more information on the standard and user states, see windowWillUseStandardFrame:defaultFrame:.

The zoom: method is typically invoked after a user clicks the window’s zoom box but may also be invoked programmatically from the performZoom: method. It performs the following steps:

  1. Invokes the windowWillUseStandardFrame:defaultFrame: method, if the delegate or the window class implements it, to obtain a “best fit” frame for the window. If neither the delegate nor the window class implements the method, uses a default frame that nearly fills the current screen, which is defined to be the screen containing the largest part of the window’s current frame.

  2. Adjusts the resulting frame, if necessary, to fit on the current screen.

  3. Compares the resulting frame to the current frame to determine whether the window’s standard frame is currently displayed. If the current frame is within a few pixels of the standard frame in size and location, it is considered a match.

  4. Determines a new frame. If the window is currently in the standard state, the new frame represents the user state, saved during a previous zoom. If the window is currently in the user state, the new frame represents the standard state, computed in step 1 above. If there is no saved user state because there has been no previous zoom, the size and location of the window do not change.

  5. Determines whether the window currently allows zooming. By default, zooming is allowed. If the window’s delegate implements the windowShouldZoom:toFrame: method, zoom: invokes that method. If the delegate doesn’t implement the method but the window does, zoom: invokes the window’s version. windowShouldZoom:toFrame: returns NO if zooming is not currently allowed.

  6. If the window currently allows zooming, sets the new frame.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSWindow.h

Constants

Window Style Masks

These constants specify the presence of a title and various buttons in a window’s border. It can be NSBorderlessWindowMask, or it can contain any of the following options, combined using the C bitwise OR operator:

enum {
   NSBorderlessWindowMask = 0,
   NSTitledWindowMask = 1 << 0,
   NSClosableWindowMask = 1 << 1,
   NSMiniaturizableWindowMask = 1 << 2,
   NSResizableWindowMask = 1 << 3,
   NSTexturedBackgroundWindowMask = 1 << 8
};
Constants
NSBorderlessWindowMask

The window displays none of the usual peripheral elements. Useful only for display or caching purposes. A window that uses NSBorderlessWindowMask can’t become key or main, unless you implement canBecomeKeyWindow or canBecomeMainWindow to return YES. Note that you can set a window’s or panel’s style mask to NSBorderlessWindowMask in Interface Builder by deselecting Title Bar in the Appearance section of the Attributes inspector.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSTitledWindowMask

The window displays a title bar.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSClosableWindowMask

The window displays a close button.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSMiniaturizableWindowMask

The window displays a minimize button.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSResizableWindowMask

The window displays a resize control.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSTexturedBackgroundWindowMask

The window displays with a metal-textured background. Additionally, the window may be moved by clicking and dragging anywhere in the window background. A bordered window with this mask gets rounded bottom corners.

Available in OS X v10.2 and later.

Declared in NSWindow.h.

Declared In
NSWindow.h

Window Levels

The standard window levels in OS X.

#define NSNormalWindowLevel          kCGNormalWindowLevel
#define NSFloatingWindowLevel        kCGFloatingWindowLevel
#define NSSubmenuWindowLevel         kCGTornOffMenuWindowLevel
#define NSTornOffMenuWindowLevel     kCGTornOffMenuWindowLevel
#define NSMainMenuWindowLevel        kCGMainMenuWindowLevel
#define NSStatusWindowLevel          kCGStatusWindowLevel
#define NSModalPanelWindowLevel      kCGModalPanelWindowLevel
#define NSPopUpMenuWindowLevel       kCGPopUpMenuWindowLevel
#define NSScreenSaverWindowLevel     kCGScreenSaverWindowLevel
#define NSDockWindowLevel            kCGDockWindowLevel
Constants
NSNormalWindowLevel

The default level for NSWindow objects.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSFloatingWindowLevel

Useful for floating palettes.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSSubmenuWindowLevel

Reserved for submenus. Synonymous with NSTornOffMenuWindowLevel, which is preferred.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSTornOffMenuWindowLevel

The level for a torn-off menu. Synonymous with NSSubmenuWindowLevel.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSModalPanelWindowLevel

The level for a modal panel.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSMainMenuWindowLevel

Reserved for the application’s main menu.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSStatusWindowLevel

The level for a status window.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSPopUpMenuWindowLevel

The level for a pop-up menu.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSScreenSaverWindowLevel

The level for a screen saver.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSDockWindowLevel

The level for the dock. (Deprecated. Deprecated. There is no replacement.)

Available in OS X v10.0 and later.

Declared in NSWindow.h.

Discussion

The stacking of levels takes precedence over the stacking of windows within each level. That is, even the bottom window in a level will obscure the top window of the next level down. Levels are listed in order from lowest to highest. These constants are mapped (using #define statements) to corresponding elements in Window Level Keys.

Display Device—Descriptions

These constants are the keys for device description dictionaries used by deviceDescription.

NSString *NSDeviceResolution;
NSString *NSDeviceColorSpaceName;
NSString *NSDeviceBitsPerSample;
NSString *NSDeviceIsScreen;
NSString *NSDeviceIsPrinter;
NSString *NSDeviceSize;
Constants
NSDeviceResolution

The corresponding value is an NSValue object containing a value of type NSSize that describes the window’s raster resolution in dots per inch (dpi).

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSDeviceColorSpaceName

The corresponding value is an NSString object giving the name of the window’s color space.

See Color Space Names in AppKit Constants Reference for a list of possible values.

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSDeviceBitsPerSample

The corresponding value is an NSNumber object containing an integer that gives the bit depth of the window’s raster image (2-bit, 8-bit, and so forth).

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSDeviceIsScreen

If there is a corresponding value, this indicates that the display device is a screen.

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSDeviceIsPrinter

If there is a corresponding value, this indicates that the display device is a printer.

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSDeviceSize

The corresponding value is an NSValue object containing a value of type NSSize that gives the size of the window’s frame rectangle.

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

Declared In
NSGraphics.h

Managing Scaling Factors

Manages scaling factors. (Deprecated. This constant no longer has an effect because the scale factor for a window backing store is dynamic and dependent on the screen on which the window is placed.)

enum {
   NSUnscaledWindowMask        = 1 << 11
};
Constants
NSUnscaledWindowMask

Specifies that the window is created without any scaling factors applied.

The client is responsible for all scaling operations in the window. Such a window returns 1.0 from its userSpaceScaleFactor method.

Currently restricted to borderless windows (NSBorderlessWindowMask).

Available in OS X v10.4 and later.

Declared in NSWindow.h.

Controlling the Look of a Window and Its Toolbar

This constant controls the look of a window and its toolbar.

enum {
   NSUnifiedTitleAndToolbarWindowMask    = 1 << 12
};
Constants
NSUnifiedTitleAndToolbarWindowMask

Specifies a window whose toolbar and title bar are rendered on a single continuous background.

Available in OS X v10.4 and later.

Declared in NSWindow.h.

Supporting Full Screen Appearance

This constant indicates that a window is in fullscreen mode.

enum {
   NSFullScreenWindowMask = 1 << 14
};
Constants
NSFullScreenWindowMask

Indicates that a window has fullscreen appearance.

A fullscreen window does not draw its titlebar, and may have special handling for its toolbar.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

NSSelectionDirection—Direction of Key View Change

These constants specify the direction a window is currently using to change the key view. They’re used by keyViewSelectionDirection.

enum {
   NSDirectSelection = 0,
   NSSelectingNext,
   NSSelectingPrevious
};
typedef NSUInteger NSSelectionDirection;
Constants
NSDirectSelection

The window isn’t traversing the key view loop.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSSelectingNext

The window is proceeding to the next valid key view.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSSelectingPrevious

The window is proceeding to the previous valid key view.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSWindowButton

These constants provide a way to access standard title bar buttons:

enum {
   NSWindowCloseButton,
   NSWindowMiniaturizeButton,
   NSWindowZoomButton,
   NSWindowToolbarButton,
   NSWindowDocumentIconButton,
   NSWindowDocumentVersionsButton = 6,
   NSWindowFullScreenButton,
};
typedef NSUInteger NSWindowButton;
Constants
NSWindowCloseButton

The close button.

Available in OS X v10.2 and later.

Declared in NSWindow.h.

NSWindowMiniaturizeButton

The minimize button.

Available in OS X v10.2 and later.

Declared in NSWindow.h.

NSWindowZoomButton

The zoom button.

Available in OS X v10.2 and later.

Declared in NSWindow.h.

NSWindowToolbarButton

The toolbar button.

Available in OS X v10.2 and later.

Declared in NSWindow.h.

NSWindowDocumentIconButton

The document icon button.

Available in OS X v10.2 and later.

Declared in NSWindow.h.

NSWindowDocumentVersionsButton

The document versions button.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

NSWindowFullScreenButton

The fullscreen icon button.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

NSRunLoop—Ordering Modes for NSWindow

These constants are passed to NSRunLoop's performSelector:target:argument:order:modes:.

enum {
   NSDisplayWindowRunLoopOrdering,
   NSResetCursorRectsRunLoopOrdering
};
Constants
NSDisplayWindowRunLoopOrdering

The priority at which windows are displayed.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSResetCursorRectsRunLoopOrdering

The priority at which cursor rects are reset.

Available in OS X v10.0 and later.

Declared in NSWindow.h.

NSWindowDepth—Window Depth

This type represents the depth, or amount of memory, devoted to a single pixel in a window or screen. A depth of 0 indicates default depth. Window depths should not be made persistent as they will not be the same across systems.

typedef int NSWindowDepth;
Discussion

Use the functions NSColorSpaceFromDepth, NSBitsPerPixelFromDepth, and NSPlanarFromDepth to extract info from an NSWindowDepth value. Use NSBestDepth to compute window depths. NSBestDepth tries to accommodate all the parameters (match or better); if there are multiple matches, it gives the closest, with matching color space first, then bps, then planar, then bpp. bpp is “bits per pixel”; 0 indicates default (same as the number of bits per plane, either bps or bps * NSNumberOfColorComponents); other values maybe used as hints to provide backing stores of different configuration: for instance, 8-bit color.

On OS X v10.6 and later, you can pass one of the explicit bit depths defined in “Explicit Window Depth Limits” to the NSWindow method setDepthLimit:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSGraphics.h

Explicit Window Depth Limits

These constants define explicit window depths that can be used with setDepthLimit:.

enum {
   NSWindowDepthTwentyfourBitRGB = 0x208,
   NSWindowDepthSixtyfourBitRGB = 0x210,
   NSWindowDepthOnehundredtwentyeightBitRGB = 0x220
};
Constants
NSWindowDepthTwentyfourBitRGB

Twenty four bit RGB depth limit.

Available in OS X v10.6 and later.

Declared in NSGraphics.h.

NSWindowDepthSixtyfourBitRGB

Sixty four bit RGB depth limit.

Available in OS X v10.6 and later.

Declared in NSGraphics.h.

NSWindowDepthOnehundredtwentyeightBitRGB

One hundred and twenty eight bit RGB depth limit.

Available in OS X v10.6 and later.

Declared in NSGraphics.h.

NSBackingStoreType—Buffered Window Drawing

These constants specify how the drawing done in a window is buffered by the window device.

enum {
   NSBackingStoreRetained     = 0,
   NSBackingStoreNonretained  = 1,
   NSBackingStoreBuffered     = 2
};
typedef NSUInteger NSBackingStoreType;
Constants
NSBackingStoreRetained

The window uses a buffer, but draws directly to the screen where possible and to the buffer for obscured portions.

You should not use this mode. It combines the limitations of NSBackingStoreNonretained with the memory use of NSBackingStoreBuffered. The original NeXTSTEP implementation was an interesting compromise that worked well with fast memory mapped framebuffers on the CPU bus—something that hasn't been in general use since around 1994. These tend to have performance problems.

In OS X v10.5 and later, requests for retained windows will result in the window system creating a buffered window, as that better matches actual use.

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSBackingStoreNonretained

The window draws directly to the screen without using any buffer.

You should not use this mode. It exists primarily for use in the original Classic Blue Box. It does not support Quartz drawing, alpha blending, or opacity. Moreover, it does not support hardware acceleration, and interferes with system-wide display acceleration. If you use this mode, your application must manage visibility region clipping itself, and manage repainting on visibility changes.

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSBackingStoreBuffered

The window renders all drawing into a display buffer and then flushes it to the screen.

You should use this mode. It supports hardware acceleration, Quartz drawing, and takes advantage of the GPU when possible. It also supports alpha channel drawing, opacity controls, using the compositor.

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSWindowOrderingMode

These constants let you specify how a window is ordered relative to another window. For more information, see orderWindow:relativeTo:.

enum {
   NSWindowAbove         =  1,
   NSWindowBelow         = -1,
   NSWindowOut             =  0
};
typedef NSInteger NSWindowOrderingMode;
Constants
NSWindowAbove

Moves the window above the indicated window.

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSWindowBelow

Moves the window below the indicated window.

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSWindowOut

Moves the window off the screen.

Available in OS X v10.0 and later.

Declared in NSGraphics.h.

NSWindowSharingType

The following constants and the related data type represent the access levels other processes can have to a window’s content.

enum {
   NSWindowSharingNone = 0,
   NSWindowSharingReadOnly = 1,
   NSWindowSharingReadWrite = 2
};
typedef NSUInteger NSWindowSharingType;
Constants
NSWindowSharingNone

The window’s contents cannot be read by another process.

Available in OS X v10.5 and later.

Declared in NSWindow.h.

NSWindowSharingReadOnly

The window’s contents can be read but not modified by another process.

Available in OS X v10.5 and later.

Declared in NSWindow.h.

NSWindowSharingReadWrite

The window’s contents can be read and modified by another process.

Available in OS X v10.5 and later.

Declared in NSWindow.h.

NSWindowBackingLocation

The following constants and the related data type represent a window’s possible backing locations.

enum {
   NSWindowBackingLocationDefault = 0,
   NSWindowBackingLocationVideoMemory = 1,
   NSWindowBackingLocationMainMemory = 2
};
typedef NSUInteger NSWindowBackingLocation;
Constants
NSWindowBackingLocationDefault

Determined by the operating system.

Available in OS X v10.5 and later.

Declared in NSWindow.h.

NSWindowBackingLocationVideoMemory

Video memory.

Available in OS X v10.5 and later.

Declared in NSWindow.h.

NSWindowBackingLocationMainMemory

Physical memory.

Available in OS X v10.5 and later.

Declared in NSWindow.h.

NSWindowNumberListOptions

The options that may be passed to the windowNumbersWithOptions: method.

enum {
   NSWindowNumberListAllApplications = 1 << 0,
   NSWindowNumberListAllSpaces = 1 << 4
};
typedef NSUInteger NSWindowNumberListOptions;
Constants
NSWindowNumberListAllApplications

The window numbers of windows visible on any space and belonging to any application.

Available in OS X v10.6 and later.

Declared in NSWindow.h.

NSWindowNumberListAllSpaces

The window numbers of windows visible on any space and belonging to the calling application.

Available in OS X v10.6 and later.

Declared in NSWindow.h.

Discussion

If the value 0 is passed instead, then the list returned from the method contains window numbers for visible windows on the active space belonging to the calling application.

NSWindowAnimationBehavior

These constants control the automatic window animation behavior used when a window is sent an orderFront: or orderOut: message.

enum {
   NSWindowAnimationBehaviorDefault = 0,
   NSWindowAnimationBehaviorNone = 2,
   NSWindowAnimationBehaviorDocumentWindow = 3,
   NSWindowAnimationBehaviorUtilityWindow = 4,
   NSWindowAnimationBehaviorAlertPanel = 5
};
typedef NSInteger NSWindowAnimationBehavior;
Constants
NSWindowAnimationBehaviorDefault

The automatic animation that’s appropriate to the window type. This is the default.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

NSWindowAnimationBehaviorNone

No automatic animation used. This may be useful when you perform your own window animation.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

NSWindowAnimationBehaviorDocumentWindow

The animation behavior that’s appropriate to the document window style.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

NSWindowAnimationBehaviorUtilityWindow

The animation behavior that’s appropriate to the utility window style.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

NSWindowAnimationBehaviorAlertPanel

The animation behavior that’s appropriate to the alert window style.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

Managing Window Collections

Window collection behaviors related to Exposé and Spaces.

enum {
   NSWindowCollectionBehaviorDefault = 0,
   NSWindowCollectionBehaviorCanJoinAllSpaces = 1 << 0,
   NSWindowCollectionBehaviorMoveToActiveSpace = 1 << 1
};
enum {
   NSWindowCollectionBehaviorManaged = 1 << 2,
   NSWindowCollectionBehaviorTransient = 1 << 3,
   NSWindowCollectionBehaviorStationary = 1 << 4,
};
enum {
   NSWindowCollectionBehaviorParticipatesInCycle = 1 << 5,
   NSWindowCollectionBehaviorIgnoresCycle = 1 << 6
};
enum {
   NSWindowCollectionBehaviorFullScreenPrimary = 1 << 7,
   NSWindowCollectionBehaviorFullScreenAuxiliary = 1 << 8
};
typedef NSUInteger NSWindowCollectionBehavior;
Constants
NSWindowCollectionBehaviorDefault

The window can be associated to one space at a time.

Available in OS X v10.5 and later.

Declared in NSWindow.h.

NSWindowCollectionBehaviorCanJoinAllSpaces

The window appears in all spaces. The menu bar behaves this way.

Available in OS X v10.5 and later.

Declared in NSWindow.h.

NSWindowCollectionBehaviorMoveToActiveSpace

Making the window active does not cause a space switch; the window switches to the active space.

Available in OS X v10.5 and later.

Declared in NSWindow.h.

NSWindowCollectionBehaviorManaged

The window participates in Spaces and Exposé. This is the default behavior if windowLevel is equal to NSNormalWindowLevel.

Available in OS X v10.6 and later.

Declared in NSWindow.h.

NSWindowCollectionBehaviorTransient

The window floats in Spaces and is hidden by Exposé. This is the default behavior if windowLevel is not equal to NSNormalWindowLevel.

Available in OS X v10.6 and later.

Declared in NSWindow.h.

NSWindowCollectionBehaviorStationary

The window is unaffected by Exposé; it stays visible and stationary, like the desktop window.

Available in OS X v10.6 and later.

Declared in NSWindow.h.

NSWindowCollectionBehaviorParticipatesInCycle

The window participates in the window cycle for use with the Cycle Through Windows Window menu item.

Available in OS X v10.6 and later.

Declared in NSWindow.h.

NSWindowCollectionBehaviorIgnoresCycle

The window is not part of the window cycle for use with the Cycle Through Windows Window menu item.

Available in OS X v10.6 and later.

Declared in NSWindow.h.

NSWindowCollectionBehaviorFullScreenPrimary

A window with this collection behavior has a fullscreen button in the upper right of its titlebar.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

NSWindowCollectionBehaviorFullScreenAuxiliary

Windows with this collection behavior can be shown on the same space as the fullscreen window.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

NSWindowOcclusionState

Specifies whether the window is occluded.

enum {
   NSWindowOcclusionStateVisible = 1UL << 1,
};
typedef NSUInteger NSWindowOcclusionState;
Constants
NSWindowOcclusionStateVisible

If set, at least part of the window is visible; if not set, the entire window is occluded. A window that has a nonrectangular shape can be entirely occluded onscreen, but if its bounding box falls into a visible region, the window is considered to be visible. Note that a completely transparent window may also be considered visible.

Available in OS X v10.9 and later.

Declared in NSWindow.h.

Additional NSModalResponse Values

These constants specify values that can be returned by endSheet: and by the completion handlers for beginSheet:completionHandler: and beginCriticalSheet:completionHandler:.

enum {
   NSModalResponseOK        = 1,
   NSModalResponseCancel    = 0
};
Constants
NSModalResponseOK

The presentation or dismissal of the sheet has finished.

Available in OS X v10.9 and later.

Declared in NSWindow.h.

NSModalResponseCancel

The presentation or dismissal of the sheet has been canceled.

Available in OS X v10.9 and later.

Declared in NSWindow.h.

Application Kit Version for Deferred Window Display Support

The version of the AppKit.framework containing a specific bug fix or capability.

#define NSAppKitVersionNumberWithDeferredWindowDisplaySupport        1019.0
Constants
NSAppKitVersionNumberWithDeferredWindowDisplaySupport

The specific version of the AppKit framework that introduced support for deferred window display. Developers should not need to use this constant unless they are writing applications for OS X v10.5 and earlier.

Available in OS X v10.6 and later.

Declared in NSWindow.h.

Application Kit Version for Custom Sheet Position

The version of the AppKit.framework containing a specific bug fix or capability.

#define NSAppKitVersionNumberWithCustomSheetPosition 686.0
Constants
NSAppKitVersionNumberWithCustomSheetPosition

The specific version of the AppKit framework that introduced custom sheet positioning. Developers should not need to use this constant unless they are writing applications for OS X v10.2 and earlier.

Available in OS X v10.3 and later.

Declared in NSWindow.h.

NSWindowDidChangeBackingPropertiesNotification User Info Properties

These constants are values that are returned in the userInfo dictionary of the NSWindowDidChangeBackingPropertiesNotification.

NSString * const NSBackingPropertyOldScaleFactorKey;
NSString * const NSBackingPropertyOldColorSpaceKey;
Constants
NSBackingPropertyOldScaleFactorKey

An NSNumber containing the old scale factor.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

NSBackingPropertyOldColorSpaceKey

An NSColorSpace instance containing the old colorspace.

Available in OS X v10.7 and later.

Declared in NSWindow.h.

Notifications

NSWindowDidBecomeKeyNotification

Posted whenever an NSWindow object becomes the key window.

The notification object is the NSWindow object that has become key. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidBecomeMainNotification

Posted whenever an NSWindow object becomes the main window.

The notification object is the NSWindow object that has become main. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidChangeScreenNotification

Posted whenever a portion of an NSWindow object’s frame moves onto or off of a screen.

The notification object is the NSWindow object that has changed screens. This notification does not contain a userInfo dictionary.

This notification is not sent in OS X versions earlier than 10.4.

Availability
Declared In
NSWindow.h

NSWindowDidChangeScreenProfileNotification

Posted whenever the display profile for the screen containing the window changes.

This notification is sent only if the window returns YES from displaysWhenScreenProfileChanges. This notification may be sent when a majority of the window is moved to a different screen (whose profile is also different from the previous screen) or when the ColorSync profile for the current screen changes.

The notification object is the NSWindow object whose profile changed. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidDeminiaturizeNotification

Posted whenever an NSWindow object is deminimized.

The notification object is the NSWindow object that has been deminimized. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidEndSheetNotification

Posted whenever an NSWindow object closes an attached sheet.

The notification object is the NSWindow object that contained the sheet. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidEndLiveResizeNotification

Posted after the user resizes a window.

This notification is sent only once for a series of window resize operations.

The notification object is the NSWindow object that was resized. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidExposeNotification

Posted whenever a portion of a nonretained NSWindow object is exposed, whether by being ordered in front of other windows or by other windows being removed from in front of it.

The notification object is the NSWindow object that has been exposed. The userInfo dictionary contains the following information:

Key

Value

@"NSExposedRect"

The rectangle that has been exposed (an NSValue object containing an NSRect).

Availability
Declared In
NSWindow.h

NSWindowDidMiniaturizeNotification

Posted whenever an NSWindow object is minimized.

The notification object is the NSWindow object that has been minimized. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidMoveNotification

Posted whenever an NSWindow object is moved.

The notification object is the NSWindow object that has moved. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidResignKeyNotification

Posted whenever an NSWindow object resigns its status as key window.

The notification object is the NSWindow object that has resigned its key window status. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidResignMainNotification

Posted whenever an NSWindow object resigns its status as main window.

The notification object is the NSWindow object that has resigned its main window status. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidResizeNotification

Posted whenever an NSWindow object’s size changes.

The notification object is the NSWindow object whose size has changed. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidUpdateNotification

Posted whenever an NSWindow object receives an update message.

The notification object is the NSWindow object that received the update message. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowWillBeginSheetNotification

Posted whenever an NSWindow object is about to open a sheet.

The notification object is the NSWindow object that is about to open the sheet. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowWillCloseNotification

Posted whenever an NSWindow object is about to close.

The notification object is the NSWindow object that is about to close. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowWillMiniaturizeNotification

Posted whenever an NSWindow object is about to be minimized.

The notification object is the NSWindow object that is about to be minimized. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowWillMoveNotification

Posted whenever an NSWindow object is about to move.

The notification object is the NSWindow object that is about to move. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowWillStartLiveResizeNotification

Posted before the user resizes a window.

This notification is sent only once for a series of window resize operations.

The notification object is the NSWindow object that is about to be live resized. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowWillEnterFullScreenNotification

Posted when the window will enter full screen mode.

The notification object is the NSWindow object will enter full screen mode. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidEnterFullScreenNotification

Posted when the window entered full screen mode.

The notification object is the NSWindow object entered full screen mode. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowWillExitFullScreenNotification

Posted when the window will exit full screen mode.

The notification object is the NSWindow object that will exit full screen mode. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidExitFullScreenNotification

Posted when the window did exit full screen mode.

The notification object is the NSWindow object that will exit full screen mode. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowWillEnterVersionBrowserNotification

Posted when the window will enter version browser mode.

The notification object is the NSWindow object that will enter version browser mode. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidEnterVersionBrowserNotification

Posted when the window will enter version browser mode.

The notification object is the NSWindow object that will enter version browser mode. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowWillExitVersionBrowserNotification

Posted when the window will exit version browser mode.

The notification object is the NSWindow object that will exit version browser mode. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidExitVersionBrowserNotification

Posted when the window did exit version browser mode.

The notification object is the NSWindow object that did exit version browser mode. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSWindow.h

NSWindowDidChangeBackingPropertiesNotification

Posted when the window backing properties change.

The notification object is the NSWindow object whose backing properties changes. This notification contains a userInfo dictionary that has backing scale and color space information. See “NSWindowDidChangeBackingPropertiesNotification User Info Properties” for the userInfo dictionary keys and values.

Availability
Declared In
NSWindow.h

NSWindowDidChangeOcclusionStateNotification

Posted when the window’s occlusion state changes.

The notification object is the NSWindow object whose occlusion state has changed. This notification does not contain a userInfo dictionary.

This notification indicates a change in the window’s occlusion state; it doesn’t indicate a change in the occlusion region. When you receive this notification, you can get the window’s current occlusion state and—based on the result—you may want to increase responsiveness and save power by halting expensive operations that the user can’t see.

Availability
Declared In
NSWindow.h