Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

NSWindow Class Reference

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

• – initWithContentRect:styleMask:backing:defer:
• – initWithContentRect:styleMask:backing:defer:screen:

Configuring Windows

• – styleMask
• – worksWhenModal
• – alphaValue
• – setAlphaValue:
• – backgroundColor
• – setBackgroundColor:
• – contentView
• – setContentView:
• – canHide
• – setCanHide:
• – hidesOnDeactivate
• – setHidesOnDeactivate:
• – collectionBehavior
• – setCollectionBehavior:
• – isOpaque
• – setOpaque:
• – hasShadow
• – setHasShadow:
• – invalidateShadow
• – autorecalculatesContentBorderThicknessForEdge:
• – setAutorecalculatesContentBorderThickness:forEdge:
• – contentBorderThicknessForEdge:
• – setContentBorderThickness:forEdge:
• – delegate
• – setDelegate:
• – canBeVisibleOnAllSpaces Deprecated in Mac OS X v10.5
• – setCanBeVisibleOnAllSpaces: Deprecated in Mac OS X v10.5

Accessing Window Information

• + defaultDepthLimit
• – windowNumber
• – gState
• – canStoreColor
• – deviceDescription
• – canBecomeVisibleWithoutLogin
• – setCanBecomeVisibleWithoutLogin:
• – sharingType
• – setSharingType:
• – backingType
• – setBackingType:
• – backingLocation
• – preferredBackingLocation
• – setPreferredBackingLocation:
• – isOneShot
• – setOneShot:
• – depthLimit
• – setDepthLimit:
• – hasDynamicDepthLimit
• – setDynamicDepthLimit:

Getting Layout Information

• + contentRectForFrameRect:styleMask:
• + frameRectForContentRect:styleMask:
• + minFrameWidthWithTitle:styleMask:
• – contentRectForFrameRect:
• – frameRectForContentRect:

Managing Windows

• – drawers
• – windowController
• – setWindowController:

Managing Sheets

• – attachedSheet
• – isSheet
• – window:willPositionSheet:usingRect:  delegate method
• – windowWillBeginSheet:  delegate method
• – windowDidEndSheet:  delegate method

Sizing

• – frame
• – setFrameOrigin:
• – setFrameTopLeftPoint:
• – constrainFrameRect:toScreen:
• – cascadeTopLeftFromPoint:
• – setFrame:display:
• – setFrame:display:animate:
• – animationResizeTime:
• – windowWillUseStandardFrame:defaultFrame:  delegate method
• – aspectRatio
• – setAspectRatio:
• – minSize
• – setMinSize:
• – maxSize
• – setMaxSize:
• – isZoomed
• – performZoom:
• – zoom:
• – windowShouldZoom:toFrame:  delegate method
• – resizeFlags
• – showsResizeIndicator
• – setShowsResizeIndicator:
• – resizeIncrements
• – setResizeIncrements:
• – preservesContentDuringLiveResize
• – setPreservesContentDuringLiveResize:
• – windowWillResize:toSize:  delegate method
• – windowDidResize:  delegate method

Sizing Content

• – contentAspectRatio
• – setContentAspectRatio:
• – contentMinSize
• – setContentMinSize:
• – setContentSize:
• – contentMaxSize
• – setContentMaxSize:
• – contentResizeIncrements
• – setContentResizeIncrements:

Managing Window Layers

• – isVisible
• – orderOut:
• – orderBack:
• – orderFront:
• – orderFrontRegardless
• – orderWindow:relativeTo:
• – level
• – setLevel:

Managing Window Frames in User Defaults

• + removeFrameUsingName:
• – setFrameUsingName:
• – setFrameUsingName:force:
• – saveFrameUsingName:
• – frameAutosaveName
• – setFrameAutosaveName:
• – stringWithSavedFrame
• – setFrameFromString:

Managing Key Status

• – isKeyWindow
• – canBecomeKeyWindow
• – makeKeyWindow
• – makeKeyAndOrderFront:
• – becomeKeyWindow
• – windowDidBecomeKey:  delegate method
• – resignKeyWindow
• – windowDidResignKey:  delegate method

Managing Main Status

• – isMainWindow
• – canBecomeMainWindow
• – makeMainWindow
• – becomeMainWindow
• – windowDidBecomeMain:  delegate method
• – resignMainWindow
• – windowDidResignMain:  delegate method

Managing Toolbars

• – toolbar
• – setToolbar:
• – toggleToolbarShown:
• – runToolbarCustomizationPalette:

Managing Attached Windows

• – childWindows
• – addChildWindow:ordered:
• – removeChildWindow:
• – parentWindow
• – setParentWindow:

Managing Window Buffers

• – isFlushWindowDisabled
• – enableFlushWindow
• – disableFlushWindow
• – flushWindow
• – flushWindowIfNeeded

Managing Default Buttons

• – defaultButtonCell
• – setDefaultButtonCell:
• – enableKeyEquivalentForDefaultButtonCell
• – disableKeyEquivalentForDefaultButtonCell

Managing Field Editors

• – fieldEditor:forObject:
• – windowWillReturnFieldEditor:toObject:  delegate method
• – endEditingFor:

Managing the Window Menu

• – isExcludedFromWindowsMenu
• – setExcludedFromWindowsMenu:

Managing Cursor Rectangles

• – areCursorRectsEnabled
• – enableCursorRects
• – disableCursorRects
• – discardCursorRects
• – invalidateCursorRectsForView:
• – resetCursorRects

Managing Title Bars

• + standardWindowButton:forStyleMask:
• – standardWindowButton:
• – showsToolbarButton
• – setShowsToolbarButton:

Managing Tooltips

• – allowsToolTipsWhenApplicationIsInactive
• – setAllowsToolTipsWhenApplicationIsInactive:

Handling Events

• + menuChanged:
• – currentEvent
• – nextEventMatchingMask:
• – nextEventMatchingMask:untilDate:inMode:dequeue:
• – discardEventsMatchingMask:beforeEvent:
• – postEvent:atStart:
• – sendEvent:
• – tryToPerform:with:

Managing Responders

• – initialFirstResponder
• – firstResponder
• – setInitialFirstResponder:
• – makeFirstResponder:

Managing the Key View Loop

• – selectKeyViewPrecedingView:
• – selectKeyViewFollowingView:
• – selectPreviousKeyView:
• – selectNextKeyView:
• – keyViewSelectionDirection
• – autorecalculatesKeyViewLoop
• – recalculateKeyViewLoop
• – setAutorecalculatesKeyViewLoop:

Handling Keyboard Events

• – keyDown:

Handling Mouse Events

• – acceptsMouseMovedEvents
• – ignoresMouseEvents
• – setIgnoresMouseEvents:
• – mouseLocationOutsideOfEventStream
• – setAcceptsMouseMovedEvents:

Bracketing Drawing Operations

• – cacheImageInRect:
• – restoreCachedImage
• – discardCachedImage

Drawing Windows

• – display
• – displayIfNeeded
• – viewsNeedDisplay
• – setViewsNeedDisplay:
• – isAutodisplay
• – setAutodisplay:
• – useOptimizedDrawing:
• – graphicsContext

Updating Windows

• – disableScreenUpdatesUntilFlush
• – update
• – windowDidUpdate:  delegate method

Exposing Windows

• – windowDidExpose:  delegate method

Dragging

• – dragImage:at:offset:event:pasteboard:source:slideBack:
• – registerForDraggedTypes:
• – unregisterDraggedTypes
• – window:shouldDragDocumentWithEvent:from:withPasteboard:  delegate method

Converting Coordinates

• – convertBaseToScreen:
• – convertScreenToBase:
• – userSpaceScaleFactor

Getting the Undo Manager

• – windowWillReturnUndoManager:  delegate method

Accessing Edited Status

• – isDocumentEdited
• – setDocumentEdited:

Managing Titles

• – title
• – setTitle:
• – setTitleWithRepresentedFilename:
• – representedFilename
• – setRepresentedFilename:
• – representedURL
• – setRepresentedURL:
• – window:shouldPopUpDocumentPathMenu:  delegate method

Accessing Screen Information

• – screen
• – deepestScreen
• – displaysWhenScreenProfileChanges
• – setDisplaysWhenScreenProfileChanges:

Moving

• – isMovableByWindowBackground
• – setMovableByWindowBackground:
• – center
• – windowWillMove:  delegate method
• – windowDidMove:  delegate method
• – windowDidChangeScreen:  delegate method
• – windowDidChangeScreenProfile:  delegate method

Closing Windows

• – performClose:
• – close
• – windowShouldClose:  delegate method
• – windowWillClose:  delegate method
• – isReleasedWhenClosed
• – setReleasedWhenClosed:

Minimizing Windows

• – isMiniaturized
• – performMiniaturize:
• – miniaturize:
• – windowWillMiniaturize:  delegate method
• – windowDidMiniaturize:  delegate method
• – deminiaturize:
• – windowDidDeminiaturize:  delegate method
• – miniwindowImage
• – setMiniwindowImage:
• – miniwindowTitle
• – setMiniwindowTitle:

Getting the Dock Tile

• – dockTile

Printing

• – print:
• – dataWithEPSInsideRect:
• – dataWithPDFInsideRect:

Providing Services

• – validRequestorForSendType:returnType:

Working with Carbon

• – initWithWindowRef:
• – windowRef

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 Mac OS X v10.0 and later.

See Also

• + frameRectForContentRect:styleMask:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setDepthLimit:
• – setDynamicDepthLimit:
• – canStoreColor

Declared In

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 “Constants” 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 Mac OS X v10.0 and later.

See Also

• + contentRectForFrameRect:styleMask:

Related Sample Code

• CocoaDragAndDrop

Declared In

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 Mac OS X v10.0 and later.

See Also

• – menu (NSResponder)

Declared In

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 “Constants” 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 Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setFrameUsingName:
• – setFrameAutosaveName:

Declared In

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 Mac OS X v10.2 and later.

See Also

• – standardWindowButton:

Declared In

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; NO otherwise.

Discussion

The NSWindow default is NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAcceptsMouseMovedEvents:

Declared In

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 Mac OS X v10.2 and later.

See Also

• – removeChildWindow:
• – childWindows
• – parentWindow
• – setParentWindow:

Related Sample Code

• GLChildWindowDemo
• TrackBall

Declared In

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; NO otherwise.

Discussion

The default is NO.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setAllowsToolTipsWhenApplicationIsInactive:

Declared In

alphaValue

Returns the window’s alpha value.

- (CGFloat)alphaValue

Return Value

The window’s alpha value.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAlphaValue:

Related Sample Code

• FunkyOverlayWindow

Declared In

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 differ in different releases of Mac OS X).

Availability

• Available in Mac OS X v10.0 and later.

Declared In

areCursorRectsEnabled

Indicates whether the window’s cursor rectangles are enabled.

- (BOOL)areCursorRectsEnabled

Return Value

YES when cursor rectangles are enabled, NO otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – enableCursorRects
• – addCursorRect:cursor: (NSView)

Declared In

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 Mac OS X v10.0 and later.

See Also

• – resizeIncrements
• – setAspectRatio:
• – setFrame:display:

Declared In

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 Mac OS X v10.1 and later.

Declared In

autorecalculatesContentBorderThicknessForEdge:

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

- (BOOL)autorecalculatesContentBorderThicknessForEdge:(NSRectEdge)edge

Parameters

edge

Border whose thickness autorecalculation status to set:

• NSMaxYEdge: Top border.

• NSMinYEdge: Bottom border.

Return Value

YES when the window autorecalculates the given border’s thickness; NO otherwise.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setAutorecalculatesContentBorderThickness:forEdge:

Declared In

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; NO otherwise.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – recalculateKeyViewLoop
• – setAutorecalculatesKeyViewLoop:

Declared In

backgroundColor

Returns the color of the window’s background.

- (NSColor *)backgroundColor

Return Value

The window’s background color.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setBackgroundColor:

Declared In

backingLocation

Indicates the window’s backing store location.

- (NSWindowBackingLocation)backingLocation

Return Value

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

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – preferredBackingLocation

Declared In

backingType

Returns the window’s backing store type.

- (NSBackingStoreType)backingType

Return Value

The backing store type.

Discussion

The possible return values are described in “Constants.”

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setBackingType:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – makeKeyWindow
• – makeKeyAndOrderFront:
• – becomeMainWindow

Declared In

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 Mac OS X v10.0 and later.

See Also

• – makeMainWindow
• – becomeKeyWindow

Declared In

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 Mac OS X v10.0 and later.

See Also

• – display

Declared In

canBecomeKeyWindow

Indicates whether the window can become the key window.

- (BOOL)canBecomeKeyWindow

Return Value

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

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, NO otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isKeyWindow
• – makeKeyWindow

Related Sample Code

• CIAnnotation
• FancyAbout
• FunkyOverlayWindow
• RoundTransparentWindow
• TrackBall

Declared In

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; NO otherwise.

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 Mac OS X v10.0 and later.

See Also

• – isMainWindow
• – makeMainWindow

Related Sample Code

• FancyAbout

Declared In

canBecomeVisibleWithoutLogin

Indicates whether the window can be displayed at the log-in window. Default: NO.

- (BOOL)canBecomeVisibleWithoutLogin

Return Value

YES when the window can be displayed at the log-in window; NO otherwise.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setCanBecomeVisibleWithoutLogin:

Declared In

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; NO otherwise.

Discussion

The default is YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setCanHide:

Declared In

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; NO otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – depthLimit
• – shouldDrawColor (NSView)

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setFrameTopLeftPoint:

Declared In

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 Mac OS X v10.0 and later.

Related Sample Code

• CocoaVideoFrameToGWorld
• VertexPerformanceTest

Declared In

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 Mac OS X v10.2 and later.

See Also

• – removeChildWindow:
• – addChildWindow:ordered:
• – parentWindow
• – setParentWindow:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – orderOut:

Related Sample Code

• ExtractMovieAudioToAIFF
• QTExtractAndConvertToAIFF
• QTExtractAndConvertToMovieFile
• SillyFrequencyLevels
• UIElementInspector

Declared In

collectionBehavior

Identifies the window’s behavior in window collections.

- (NSWindowCollectionBehavior)collectionBehavior;

Return Value

The collection behavior identifier.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setCollectionBehavior:

Declared In

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 Mac OS X v10.0 and later.

Related Sample Code

• iSpend

Declared In

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 Mac OS X v10.3 and later.

See Also

• – setContentAspectRatio:

Declared In

contentBorderThicknessForEdge:

Indicates the thickness of a given border of the window.

- (CGFloat)contentBorderThicknessForEdge:(NSRectEdge)edge

Parameters

edge

Border whose thickness to get:

• NSMaxYEdge: Top border.

• NSMinYEdge: Bottom border.

Return Value

Thickness of the given border, in points.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setContentBorderThickness:forEdge:

Declared In

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 Mac OS X v10.3 and later.

See Also

• – setContentMaxSize:
• – contentMinSize

Declared In

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 Mac OS X v10.3 and later.

See Also

• – setContentMinSize:
• – contentMaxSize

Declared In

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 “Constants” 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 Mac OS X v10.3 and later.

See Also

• – frameRectForContentRect:
• + contentRectForFrameRect:styleMask:

Declared In

contentResizeIncrements

Returns the window’s content-view resizing increments.

- (NSSize)contentResizeIncrements

Return Value

The window’s content-view resizing increments.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setContentResizeIncrements:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setContentView:

Related Sample Code

• CocoaDVDPlayer
• FunkyOverlayWindow
• LiveVideoMixer2
• VideoViewer
• WhackedTV

Declared In

convertBaseToScreen:

Converts a given point from the window’s base coordinate system to the screen coordinate system.

- (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 Mac OS X v10.0 and later.

See Also

• – convertScreenToBase:
• – convertPoint:toView: (NSView)

Declared In

convertScreenToBase:

Converts a given point from the screen coordinate system to the window’s base coordinate system.

- (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 Mac OS X v10.0 and later.

See Also

• – convertBaseToScreen:
• – convertRect:fromView: (NSView)

Declared In

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 Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.0 and later.

See Also

• – dataWithEPSInsideRect: (NSView)
• – writeEPSInsideRect:toPasteboard: (NSView)

Declared In

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 Mac OS X v10.0 and later.

See Also

• – dataWithPDFInsideRect: (NSView)
• – writePDFInsideRect:toPasteboard: (NSView)

Declared In

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 Mac OS X v10.0 and later.

See Also

• – screen
• + deepestScreen (NSScreen)

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setDefaultButtonCell:
• – disableKeyEquivalentForDefaultButtonCell
• – enableKeyEquivalentForDefaultButtonCell

Declared In

delegate

Returns the window’s delegate.

- (id)delegate

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDelegate:

Related Sample Code

• FancyAbout
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

deminiaturize:

Deminimizes 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 Mac OS X v10.0 and later.

See Also

• – miniaturize:
• – styleMask

Declared In

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 Mac OS X v10.0 and later.

See Also

• + defaultDepthLimit
• – setDepthLimit:
• – setDynamicDepthLimit:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – deviceDescription (NSScreen)
• – bestRepresentationForDevice: (NSImage)
• – colorUsingColorSpaceName: (NSColor)

Related Sample Code

• CocoaDVDPlayer

Declared In

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 Mac OS X v10.0 and later.

See Also

• – enableCursorRects

Declared In

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 (unnested) enableFlushWindow message is sent.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• CocoaDVDPlayer

Declared In

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 Mac OS X v10.0 and later.

See Also

• – defaultButtonCell
• – enableKeyEquivalentForDefaultButtonCell

Declared In

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.

Availability

• Available in Mac OS X v10.4 and later.

Related Sample Code

• GLSLShowpiece

Declared In

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 Mac OS X v10.0 and later.

See Also

• – cacheImageInRect:
• – restoreCachedImage
• – display

Declared In

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 Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.0 and later.

See Also

• – discardEventsMatchingMask:beforeEvent: (NSApplication)

Declared In

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 Mac OS X v10.0 and later.

See Also

• – display (NSView)
• – displayIfNeeded
• – isAutodisplay

Related Sample Code

• GLChildWindowDemo

Declared In

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 Mac OS X v10.0 and later.

See Also

• – display
• – displayIfNeeded (NSView)
• – setNeedsDisplay: (NSView)
• – isAutodisplay

Declared In

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; NO otherwise.

Discussion

The default value is NO.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setDisplaysWhenScreenProfileChanges:

Related Sample Code

• VideoViewer

Declared In

dockTile

Provides the application’s Dock tile.

- (NSDockTile *)dockTile

Return Value

The application’s Dock tile.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

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 Mac 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 transfered to the destination.

sourceObject

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

slideBack

Specifies whether the drag image should slide back to imageLocation if it's rejected by the drag destination. Pass YES to specify slideback behavior, NO to specify otherwise.

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 Mac OS X v10.0 and later.

See Also

• – dragImage:at:offset:event:pasteboard:source:slideBack: (NSView)

Declared In

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 Mac OS X v10.0 and later.

Declared In

enableCursorRects

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

- (void)enableCursorRects

Availability

• Available in Mac OS X v10.0 and later.

Declared In

enableFlushWindow

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

- (void)enableFlushWindow

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• CocoaDVDPlayer

Declared In

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 Mac OS X v10.0 and later.

See Also

• – defaultButtonCell
• – disableKeyEquivalentForDefaultButtonCell

Declared In

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 Mac OS X v10.0 and later.

See Also

• – fieldEditor:forObject:
• – windowWillReturnFieldEditor:toObject:

Declared In

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 Mac OS X v10.0 and later.

Declared In

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – makeFirstResponder:
• – acceptsFirstResponder (NSResponder)

Declared In

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 Mac OS X v10.0 and later.

See Also

• – flushWindowIfNeeded
• – disableFlushWindow
• – enableFlushWindow

Related Sample Code

• GLChildWindowDemo

Declared In

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 Mac OS X v10.0 and later.

See Also

• – disableFlushWindow
• – enableFlushWindow

Declared In

frame

Returns the window’s frame rectangle.

- (NSRect)frame

Return Value

The frame rectangle of the window in screen coordinates.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – screen
• – deepestScreen

Related Sample Code

• BasicCocoaAnimations
• FunkyOverlayWindow
• iSpend
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setFrameUsingName:

Declared In

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 “Constants” 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 Mac OS X v10.3 and later.

See Also

• – contentRectForFrameRect:
• + frameRectForContentRect:styleMask:

Related Sample Code

• BasicCocoaAnimations

Declared In

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 Mac OS X v10.4 and later.

Declared In

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 Mac OS X v10.0 and later.

Declared In

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; NO otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDynamicDepthLimit:

Declared In

hasShadow

Indicates whether the window has a shadow.

- (BOOL)hasShadow

Return Value

YES when the window has a shadow; NO otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setHasShadow:
• – invalidateShadow

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setHidesOnDeactivate:

Declared In

ignoresMouseEvents

Indicates whether the window is transparent to mouse events.

- (BOOL)ignoresMouseEvents

Return Value

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

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – setIgnoresMouseEvents:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setInitialFirstResponder:
• – setNextKeyView: (NSView)

Declared In

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

Location 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. Either it can be NSBorderlessWindowMask, or it can contain any of the options described in “Constants,” 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 “Constants.”

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 Mac OS X v10.0 and later.

See Also

• – orderFront:
• – setTitle:
• – setOneShot:
• – initWithContentRect:styleMask:backing:defer:screen:

Related Sample Code

• CIAnnotation
• FancyAbout
• FunkyOverlayWindow
• TrackBall
• UIElementInspector

Declared In

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

Location 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 either NSBorderlessWindowMask, or it can contain any of the options described in “Constants,” 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; possible values are described in “Constants.”

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 where the window’s content rectangle is drawn if the window is to be drawn in a screen other than the main screen. The content rectangle is drawn relative to the bottom-left corner of screen. When nil, the content rectangle is drawn on the main screen.

Return Value

The initialized window.

Discussion

The main 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 main screen is the one where the origin of the screen coordinate system is located.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – orderFront:
• – setTitle:
• – setOneShot:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – windowRef

Related Sample Code

• CarbonInCocoa

Declared In

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 Mac OS X v10.0 and later.

See Also

• – resetCursorRects
• – resetCursorRects (NSView)

Declared In

invalidateShadow

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

- (void)invalidateShadow

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – hasShadow
• – setHasShadow:

Declared In

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; NO otherwise.

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAutodisplay:
• – displayIfNeeded
• – setNeedsDisplay: (NSView)

Declared In

isDocumentEdited

Indicates whether the window’s document has been edited.

- (BOOL)isDocumentEdited

Return Value

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

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

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; NO otherwise.

Discussion

The default initial setting is NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setExcludedFromWindowsMenu:

Declared In

isFlushWindowDisabled

Indicates whether the window’s flushing ability is disabled.

- (BOOL)isFlushWindowDisabled

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – disableFlushWindow
• – enableFlushWindow

Declared In

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; NO otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isMainWindow
• – makeKeyWindow

Declared In

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, NO otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isKeyWindow
• – makeMainWindow

Declared In

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 Mac OS X v10.0 and later.

See Also

• – miniaturize:

Declared In

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; NO otherwise.

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 Mac OS X v10.2 and later.

See Also

• – setMovableByWindowBackground:

Declared In

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; NO otherwise.

Discussion

The default is NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setOneShot:

Declared In

isOpaque

Indicates whether the window is opaque.

- (BOOL)isOpaque

Return Value

YES when the window is opaque; NO otherwise.

Discussion

The default is YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setOpaque:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setReleasedWhenClosed:

Declared In

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.

Discussion

Sheets are created using the NSPanel subclass.

Availability

• Available in Mac OS X v10.1 and later.

Declared In

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); NO otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – visibleRect (NSView)

Related Sample Code

• GLChildWindowDemo
• SimpleCocoaJavaMovie
• SimpleCocoaJavaMovieCocoa

Declared In

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 windowWillResize:toSize:, 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 Mac OS X v10.0 and later.

See Also

• – zoom:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – selectNextKeyView:
• – nextKeyView (NSView)
• – performMnemonic: (NSView)

Declared In

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 “Constants.”

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – selectNextKeyView:
• – selectPreviousKeyView:

Declared In

level

Returns the window level of the window.

- (NSInteger)level

Return Value

The window level.

Discussion

See “Constants” for a list of possible values.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setLevel:

Declared In

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; NO otherwise.

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 Mac OS X v10.0 and later.

See Also

• – becomeFirstResponder (NSResponder)
• – resignFirstResponder (NSResponder)

Related Sample Code

• Aperture Edit Plugin - Borders & Titles
• CustomSave
• Sketch-112
• WhackedTV

Declared In

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 Mac OS X v10.0 and later.

See Also

• – orderFront:
• – orderBack:
• – orderOut:
• – orderWindow:relativeTo:
• – setLevel:

Related Sample Code

• GridCalendar
• QTAudioExtractionPanel
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus
• WhackedTV

Declared In

makeKeyWindow

Makes the window the key window.

- (void)makeKeyWindow

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – makeMainWindow
• – becomeKeyWindow
• – isKeyWindow

Declared In

makeMainWindow

Makes the window the main window.

- (void)makeMainWindow

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – makeKeyWindow
• – becomeMainWindow
• – isMainWindow

Declared In

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setMaxSize:
• – minSize
• – aspectRatio
• – resizeIncrements

Declared In

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 Mac OS X v10.0 and later.

See Also

• – deminiaturize:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setMiniwindowImage:
• – miniwindowTitle

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setMiniwindowTitle:
• – miniwindowImage

Declared In

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setMinSize:
• – maxSize
• – aspectRatio
• – resizeIncrements

Declared In

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 Mac OS X v10.0 and later.

See Also

• – currentEvent (NSApplication)

Declared In

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 nonmatching masks are removed from 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 Mac OS X v10.0 and later.

See Also

• – nextEventMatchingMask:untilDate:inMode:dequeue: (NSApplication)

Related Sample Code

• Sketch-112

Declared In

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 Mac OS X v10.0 and later.

See Also

• – nextEventMatchingMask:untilDate:inMode:dequeue: (NSApplication)

Related Sample Code

• CIAnnotation
• LiveVideoMixer2
• LiveVideoMixer3
• ThreadsExportMovie

Declared In

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 Mac OS X v10.0 and later.

See Also

• – orderFront:
• – orderOut:
• – orderWindow:relativeTo:
• – makeKeyAndOrderFront:
• – level

Declared In

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – orderBack:
• – orderOut:
• – orderWindow:relativeTo:
• – makeKeyAndOrderFront:
• – level

Related Sample Code

• Aperture Edit Plugin - Borders & Titles
• CocoaDVDPlayer
• FunkyOverlayWindow
• TrackBall
• UIElementInspector

Declared In

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 Mac OS X v10.0 and later.

See Also

• – orderFront:
• – level

Declared In

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – orderFront:
• – orderBack:
• – orderWindow:relativeTo:
• – setReleasedWhenClosed:

Related Sample Code

• EnhancedDataBurn
• GridCalendar
• ImageClient
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

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 Mac OS X v10.0 and later.

See Also

• – orderFront:
• – orderBack:
• – orderOut:
• – makeKeyAndOrderFront:
• – level
• – windowNumber

Declared In

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 Mac OS X v10.2 and later.

See Also

• – removeChildWindow:
• – childWindows
• – addChildWindow:ordered:
• – setParentWindow:

Related Sample Code

• FunkyOverlayWindow
• GLChildWindowDemo

Declared In

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 Mac OS X v10.0 and later.

See Also

• – styleMask
• – performMiniaturize:

Related Sample Code

• QTMetadataEditor

Declared In

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 Mac OS X v10.0 and later.

See Also

• – close
• – styleMask
• – performClose:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – styleMask
• – zoom:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – postEvent:atStart:

Declared In

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 Mac OS X v10.5 and later.

See Also

• – setPreferredBackingLocation:
• – backingLocation

Declared In

preservesContentDuringLiveResize

Returns a Boolean value that indicates whether the window tries to optimize live 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; NO otherwise.

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 Mac OS X v10.4 and later.

See Also

• – setPreservesContentDuringLiveResize:
• – preservesContentDuringLiveResize (NSView)

Declared In

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 Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.4 and later.

See Also

• – selectKeyViewFollowingView:
• – selectKeyViewPrecedingView:
• – setAutorecalculatesKeyViewLoop:

Declared In

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 informal 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 Mac OS X v10.0 and later.

See Also

• – unregisterDraggedTypes

Declared In

removeChildWindow:

Detaches a given child window from the window.

- (void)removeChildWindow:(NSWindow *)childWindow

Parameters

childWindow

The child window to detach.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – addChildWindow:ordered:
• – childWindows
• – parentWindow
• – setParentWindow:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setRepresentedFilename:

Declared In

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.

You can customize the file icon in the tile 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 Mac OS X v10.5 and later.

See Also

• – setRepresentedURL:
• – window:shouldDragDocumentWithEvent:from:withPasteboard:

Declared In

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 Mac OS X v10.0 and later.

Related Sample Code

• TextLinks

Declared In

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 Mac OS X v10.0 and later.

See Also

• – becomeKeyWindow
• – resignMainWindow

Declared In

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 Mac OS X v10.0 and later.

See Also

• – becomeMainWindow
• – resignKeyWindow

Declared In

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 Mac OS X v10.0 and later.

Declared In

resizeIncrements

Returns the window’s resizing increments.

- (NSSize)resizeIncrements

Return Value

The window’s resizing increments.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setResizeIncrements:
• – setAspectRatio:
• – setFrame:display:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – discardCachedImage
• – display

Declared In

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 Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.0 and later.

See Also

• – stringWithSavedFrame

Declared In

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 Mac OS X v10.0 and later.

See Also

• – deepestScreen

Related Sample Code

• CocoaDVDPlayer
• iSpend
• QTQuartzPlayer

Declared In

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 Mac OS X v10.0 and later.

See Also

• – selectKeyViewPrecedingView:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – selectKeyViewFollowingView:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – selectPreviousKeyView:
• – selectKeyViewFollowingView:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – selectNextKeyView:
• – selectKeyViewPrecedingView:

Declared In

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 Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.0 and later.

See Also

• – acceptsMouseMovedEvents

Declared In

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 Mac OS X v10.3 and later.

See Also

• – allowsToolTipsWhenApplicationIsInactive

Declared In

setAlphaValue:

Applies a given alpha value to the entire window.

- (void)setAlphaValue:(CGFloat)windowAlpha

Parameters

windowAlpha

The alpha value to apply.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – alphaValue

Related Sample Code

• FunkyOverlayWindow
• JavaSplashScreen
• RoundTransparentWindow
• UIElementInspector

Declared In

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 Mac OS X v10.0 and later.

See Also

• – aspectRatio
• – setFrame:display:

Declared In

setAutodisplay:

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

- (void)setAutodisplay:(BOOL)autodisplay

Parameters

autodisplay

YES to have the window automatically display views that need to be displayed; NO to specify otherwise.

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isAutodisplay
• – displayIfNeeded
• – displayIfNeeded (NSView)

Declared In

setAutorecalculatesContentBorderThickness:forEdge:

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

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

Parameters

autorecalculateContentBorderThickness

YES to have the window calculate the thickness of edge automatically; NO otherwise.

edge

Border whose thickness autorecalculation status to set:

• NSMaxYEdge: Top border.

• NSMinYEdge: Bottom border.

Special Considerations

Turning off a border’s autorecalculation status sets its border thickness to 0.0.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – autorecalculatesContentBorderThicknessForEdge:
• – contentBorderThicknessForEdge:

Declared In

setAutorecalculatesKeyViewLoop:

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

- (void)setAutorecalculatesKeyViewLoop:(BOOL)autorecalculateKeyViewLoop

Parameters

autorecalculateKeyViewLoop

YES to recalculate the key view loop automatically; NO otherwise.

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 Mac OS X v10.4 and later.

See Also

• – autorecalculatesKeyViewLoop
• – recalculateKeyViewLoop

Declared In

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 Mac OS X v10.0 and later.

See Also

• – backgroundColor

Related Sample Code

• JavaSplashScreen
• RoundTransparentWindow
• UIElementInspector

Declared In

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 Mac OS X v10.0 and later.

See Also

• – backingType
• – initWithContentRect:styleMask:backing:defer:
• – initWithContentRect:styleMask:backing:defer:screen:

Declared In

setCanBecomeVisibleWithoutLogin:

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

- (void)setCanBecomeVisibleWithoutLogin:(BOOL)canBecomeVisibleWithoutLogin

Parameters

canBecomeVisibleWithoutLogin

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

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – canBecomeVisibleWithoutLogin

Declared In

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

YES specifies that the window can be hidden when its application becomes hidden; NO specifies otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – canHide

Declared In

setCollectionBehavior:

Specifies the window’s behavior in window collections.

- (void)setCollectionBehavior:(NSWindowCollectionBehavior)collectionBehavior;

Parameters

collectionBehavior

The collection behavior identifier to set.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – collectionBehavior

Declared In

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 Mac OS X v10.3 and later.

See Also

• – contentAspectRatio

Declared In

setContentBorderThickness:forEdge:

Specifies the thickness of a given border of the window.

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

Parameters

borderThickness

Thickness for edge, in points.

edge

Border whose thickness to set:

• NSMaxYEdge: Top border.

• NSMinYEdge: Bottom border.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – contentBorderThicknessForEdge:

Declared In

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:. This method takes precedence over setMaxSize:.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – contentMaxSize
• – setContentMinSize:

Declared In

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:. This method takes precedence over setMinSize:.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – contentMinSize
• – setContentMaxSize:

Declared In

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 resizer 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 Mac OS X v10.3 and later.

See Also

• – contentResizeIncrements

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setFrame:display:
• + contentRectForFrameRect:styleMask:
• + frameRectForContentRect:styleMask:

Related Sample Code

• CocoaDVDPlayer
• CocoaVideoFrameToGWorld
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus
• VideoViewer

Declared In

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 Mac OS X v10.0 and later.

See Also

• – contentView
• – setContentSize:

Related Sample Code

• CustomSave
• FunkyOverlayWindow
• GLChildWindowDemo

Declared In

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 Mac OS X v10.0 and later.

See Also

• – defaultButtonCell
• – disableKeyEquivalentForDefaultButtonCell
• – enableKeyEquivalentForDefaultButtonCell

Declared In

setDelegate:

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

- (void)setDelegate:(id)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 Mac OS X v10.0 and later.

See Also

• – delegate
• – tryToPerform:with:
• – sendAction:to:from: (NSApplication)

Related Sample Code

• AudioBurn
• DataBurn
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus
• Verification

Declared In

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – depthLimit
• + defaultDepthLimit
• – setDynamicDepthLimit:

Declared In

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 Mac OS X v10.4 and later.

See Also

• – displaysWhenScreenProfileChanges

Declared In

setDocumentEdited:

Specifies whether the window’s document has been edited.

- (void)setDocumentEdited:(BOOL)documentEdited

Parameters

documentEdited

YES to specify that the window’s document has been edited; NO to specify otherwise.

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 Mac OS X v10.0 and later.

Declared In

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

YES specifies a dynamic depth limit; NO specifies otherwise.

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – hasDynamicDepthLimit
• + defaultDepthLimit

Declared In

setExcludedFromWindowsMenu:

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

- (void)setExcludedFromWindowsMenu:(BOOL)excludedFromWindowsMenu

Parameters

excludedFromWindowsMenu

YES to specify that the window is to be omitted from the application’s Windows menu; NO to specify otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isExcludedFromWindowsMenu

Related Sample Code

• VertexPerformanceTest

Declared In

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.

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 Mac OS X v10.0 and later.

See Also

• – frame
• – setFrameFromString:
• – setFrameOrigin:
• – setFrameTopLeftPoint:
• – setFrameUsingName:

Related Sample Code

• ColorMatching
• FunkyOverlayWindow
• SimpleCocoaMovie
• SimpleCocoaMovieQT

Declared In

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.

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 Mac OS X v10.0 and later.

Related Sample Code

• iSpend
• QTQuartzPlayer

Declared In

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 Mac OS X v10.0 and later.

See Also

• + removeFrameUsingName:
• – stringWithSavedFrame
• – setFrameFromString:

Declared In

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

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 Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setFrame:display:
• – setFrameTopLeftPoint:

Related Sample Code

• FunkyOverlayWindow

Declared In

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 Mac OS X v10.0 and later.

See Also

• – cascadeTopLeftFromPoint:
• – setFrame:display:
• – setFrameOrigin:

Related Sample Code

• CocoaDVDPlayer
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

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; NO otherwise.

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 Mac OS X v10.0 and later.

See Also

• – setFrameAutosaveName:
• + removeFrameUsingName:
• – stringWithSavedFrame
• – setFrameFromString:

Declared In

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

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

Parameters

frameName

The name of the frame to read.

force

YES to use setFrameUsingName: on a nonresizable window; NO to fail on a nonresizable window.

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

setHasShadow:

Specifies whether the window has a shadow.

- (void)setHasShadow:(BOOL)hasShadow

Parameters

hasShadow

YES specifies that the window has a shadow; NO specifies otherwise.

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – hasShadow
• – invalidateShadow

Related Sample Code

• FunkyOverlayWindow
• JavaSplashScreen
• RoundTransparentWindow

Declared In

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 Mac OS X v10.0 and later.

See Also

• – hidesOnDeactivate

Declared In

setIgnoresMouseEvents:

Specifies whether the window is transparent to mouse clicks and other mouse events, allowing overlay windows.

- (void)setIgnoresMouseEvents:(BOOL)ignoreMouseEvents

Parameters

ignoreMouseEvents

YES to have the window ignore mouse events; NO to specify otherwise.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – ignoresMouseEvents

Related Sample Code

• FunkyOverlayWindow

Declared In

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 Mac OS X v10.0 and later.

See Also

• – initialFirstResponder

Declared In

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 “Constants.”

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 Mac OS X v10.0 and later.

See Also

• – level
• – orderWindow:relativeTo:
• – orderFront:
• – orderBack:

Related Sample Code

• FunkyOverlayWindow
• JavaSplashScreen
• RoundTransparentWindow
• UIElementInspector

Declared In

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:. 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 Mac OS X v10.0 and later.

See Also

• – maxSize
• – setMinSize:
• – setAspectRatio:
• – setResizeIncrements:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – miniwindowImage
• – isMiniaturized

Declared In

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.