Inherits From:
NSResponder : NSObject
Conforms To:
NSCoding (from NSResponder)
NSObject (from NSObject)
Declared In:
AppKit/NSWindow.h
- makeKeyAndOrderFront: | Moves the NSWindow to the front and makes it the key window. |
- makeFirstResponder: | Sets the first responder in the NSWindow. |
- fieldEditor:forObject: | Returns the shared text object for the NSWindow. |
- setContentView: | Sets the root-level NSView in the NSWindow. |
- representedFilename | Returns the filename whose contents the NSWindow presents. |
- setDocumentEdited: | Sets whether the NSWindow's represented file needs to be saved. |
- setTitle: | Sets the title of the NSWindow. |
- setTitleWithRepresentedFilename: | Sets the title of the NSWindow in a readable format for filenames. |
You typically set windows up using Interface Builder, which allows you to position them, set up many of their visual and behavioral attributes, and lay out views in them. The programmatic work you do with windows more often involves bringing them on and off the screen; changing dynamic attributes such as the window's title; running modal windows to restrict user input; and assigning a delegate that can monitor certain of the window's actions, such as closing, zooming, and resizing.
You create an NSWindow programmatically through one of the initWithContentRect:...
methods by specifying, among other attributes, the size and location of its content rectangle. The frame rectangle is derived from the dimensions of the content rectangle. Various sections below describe other attributes you can specify at initialization and afterward.
When it's created, an NSWindow automatically creates two NSViews: An opaque frame view that fills the frame rectangle and draws the border, title bar, other peripheral elements, and background, and a transparent content view that fills the content rectangle. The frame view and its peripheral elements are private objects that your application can't access directly. The content view is the "highest" accessible NSView in the NSWindow; you can replace the default content view with an NSView of your own creation using the setContentView:
method. The NSWindow determines the placement of the content view; you can't position it using NSView's setFrame...
methods, but must use NSWindow's placement methods, described in "Windows on the Screen" below.
You add other NSViews to the NSWindow as subviews of the content view or as subviews of any of the content view's subviews, and so on, through NSView's addSubview:
method. This tree of NSViews is called the NSWindow's view hierarchy. When an NSWindow is told to display itself, it does so by sending display...
messages to the top-level NSView in its view hierarchy. Because displaying is carried out in a determined order, the content view (which is drawn first) may be wholly or partially obscured by its subviews, and these subviews may be obscured by their subviews (and so on).
initWithContentRect:styleMask:backing:defer:
method. There are four possible style elements, specifiable by combining their mask values using the C bitwise OR operator:
Element | Mask Value |
---|---|
A title bar | NSTitledWindowMask |
A close button | NSClosableWindowMask |
A miniaturize button | NSMiniaturizableWindowMask |
A resize bar, border, or box | NSResizableWindowMask |
You can also specify NSBorderlessWindowMask, in which case none of these style elements is used.
setLevel:
.) Placing an NSWindow on the screen is accomplished with the setFrame:display:
method and its variants setFrameOrigin:
and setFrameTopLeftPoint:
. Ordering takes place in two ways. The setLevel:
method puts an NSWindow into a group, such as that for standard windows, floating windows (for example, palettes and some inspector panels), menus, and so on. The orderWindow:relativeTo:
method orders an NSWindow within its level in front of or in back of another. Convenience methods for ordering include makeKeyAndOrderFront:
, orderFront:
and orderBack:
, as well as orderOut:
, which removes an NSWindow from the screen. The isVisible
method tells whether an NSWindow is on or off the screen. You can also set a window to be removed from the screen automatically when its application isn't active using setHidesOnDeactivate:
.NSWindow offers several means of constraining and adjusting window placement:
setMinSize:
and setMaxSize:
limit the user's ability to resize the NSWindow (you can still set it to any size programmatically). Similarly, setAspectRatio:
keeps a window's width and height at the same proportions as the user resizes it, and setResizeIncrements:
makes the window resize in discrete amounts larger than a single pixel. (Aspect ratio and resize increments are mutually exclusive attributes. See the setAspectRatio:
and setResizeIncrements:
method descriptions for more information.)
The constrainFrameRect:toScreen:
method adjusts a proposed frame rectangle so that it lies on the screen in such a way that the user can move and resize a window. Note that any NSWindow with a title bar automatically constrains itself to the screen. The cascadeTopLeftFromPoint:
method shifts the top left point by an amount that allows one NSWindow to be placed relative to another so that both their title bars are visible.
The zoom:
method toggles the size and location of a window between its standard state, as determined by the application, and its user state-a new size and location the user may have set by moving or resizing the window.
Finally, the center
method places an NSWindow in the most prominent location on the screen, one suitable for important messages and attention panels.
Closely related to window ordering is the idea of opening or closing an NSWindow. Normally, opening is accomplished simply by ordering the NSWindow in front of or in back of another that's on screen. Closing a window involves explicit use of either the close
method, which simply removes the NSWindow from the screen, or performClose:
, which highlights the close button as though the user clicked it. Closing an NSWindow involves at least removing it from the screen but adds the possibility of disposing of it altogether. The setReleasedWhenClosed:
method sets whether an NSWindow releases itself when it receives a close message. An NSWindow's delegate is also notified when it's about to close, as described in the "Notifications and the NSWindow's Delegate" section.
Miniaturizable windows can be removed from the screen and replaced by a smaller counterpart, whether a freestanding miniwindow or, on Microsoft Windows, a button in the task bar. The miniaturize:
and deminiaturize:
methods reduce and reconstitute an NSWindow, and performMiniaturize:
simulates the user clicking the NSWindow's miniaturize button. You can also set the image and title displayed in a freestanding miniwindow by sending setMiniwindowImage:
and setMiniwindowTitle:
messages to the NSWindow object.
An NSWindow can store its placement in the user defaults system, so that it appears in the same location the next time the user starts the application. The saveFrameUsingName:
method stores the frame rectangle, and setFrameUsingName:
sets it from the value in user defaults. You can also use the setFrameAutosaveName:
method to have an NSWindow save the frame rectangle any time it changes. To expunge a frame rectangle from the defaults system, use the class method removeFrameUsingName:
.
setTitle:
method puts an arbitrary string on the title bar. The setTitleWithRepresentedFilename:
method formats a filename in the title bar in a readable format (which varies with the platform) and associates the NSWindow with that file. You can set the associated file without changing the title using setRepresentedFilename:
. You can use the association between the NSWindow and the file in any way you see fit. One convenience offered by NSWindow is marking the file as being edited, so that you can prompt the user to save it on closing the window. The method for marking this is setDocumentEdited:
. When the window closes, its delegate can check it with isDocumentEdited
to see whether the document needs to be saved.
Most OPENSTEP applications include a submenu that displays the titles of windows, called the Windows menu. This submenu automatically lists windows that have a title bar and are resizable and that can become the main window (as described under "Event Handling"). When you change an NSWindow's title, this change is also automatically reflected in the Windows menu. You can exclude a window that would otherwise be listed by sending it a setExcludedFromWindowsMenu:
message.
windowNumber
method. Each window also has a PostScript graphics state that most NSViews share for drawing (NSViews can create their own as well). The gstate
method returns its identifier. The five attributes under direct NSWindow control are:
setBackingType:
method.
The last argument to initWithContentRect:styleMask:backing:defer:
specifies whether the NSWindow creates its window device immediately or only when it's moved on screen. Deferring creation of the window device can offer some performance gain for windows that aren't displayed immediately because it reduces the amount of work that needs to be performed up front. Deferring creation of the window device is particularly useful when creation of the NSWindow itself can't be deferred or when an NSWindow is needed for purposes other than displaying content. Submenus with key equivalents, for example, must exist for the key equivalents to work, but may never actually be displayed.
Memory can also be saved by destroying the window device when the window is removed from the screen. The setOneShot:
method controls this behavior. One-shot window devices exist only when their NSWindows are on screen.
Like the display hardware, a window device's buffer has a depth, or a limit to the memory allotted each pixel. Buffered and retained windows start out with a default window depth of 2 bits per pixel, and this depth grows to the window device's limit as the NSWindow draws richer images (more shades of gray, more colors). A window device's depth is set using the setDepthLimit:
method, which takes as an argument a window depth limit created using the NSBestDepth
function.
If an NSWindow draws color into its buffer and there's a color screen available, the Window Server automatically promotes the window's depth (up to its limit). This happens whether or not the window is actually on a color screen; similarly, if the user drags a window that displays color from a color screen to a monochrome screen, it remains at its richer depth. In both cases, the window's depth is greater than the screen can properly display. Keeping a window's depth at its richest preserves the displayed image, but it may produce undesired results such as dithering on a more limited screen and does causes slight performance reduction when the window buffer is deeper than the screen requires. You can set an NSWindow to keep its depth at the limit of the screen it's on with the setDynamicDepthLimit:
method. When it's moved to a new screen, a window with a dynamic depth limit is redrawn into the newly adjusted buffer. Making a window's depth limit dynamic overrides the limit set using setDepthLimit:
, and removing the dynamic limit reverts the static limit to the default.
display
and setViewsNeedDisplay:
methods, respectively. A displayIfNeeded
message causes the NSWindow's views to display only if they've been marked as needing display. Normally, any time an NSView is marked as needing display, the NSWindow makes note of this fact and automatically displays itself shortly after. This automatic display is typically performed on each pass through the event loop, but can be turned off using the setAutodisplay:
method. If you turn off autodisplay for an NSWindow, you're then responsible for displaying it whenever necessary.
A related mechanism is that of updating. On each pass through the event loop, the application object invokes its updateWindows
method, which sends an update
message to each NSWindow. Subclasses of NSWindow can override this method to examine the state of the application and change their own state or appearance accordingly-enabling or disabling menus, buttons, and other controls based on the object that's selected, for example.
In addition to displaying itself on the screen, an NSWindow can print itself in its entirety, just as an NSView can. The print:
method runs the application's Print panel and causes the NSWindow's frame view to print itself. The fax:
and dataWithEPSInsideRect:
methods behave similarly. See the NSView class specification for more information on printing.
sendEvent:
message. A key event is directed at the key window, while a mouse event is directed at whatever window lies under the cursor. If an event affects the window directly-resizing or moving it, for example-it performs the appropriate operation itself and sends messages to its delegate informing it of its intentions, thus allowing your application to intercede. The window sends other events up its responder chain from the appropriate starting point: the first responder for a key event, the view under the cursor for a mouse event. These events are then typically handled by some view object in the window. See the NSView and NSEvent class specifications for more information on how to intercept and handle events.The following sections describe aspects of events not directly related to handling individual events. These include changing the key and main windows, changing the first responder by keyboard rather than mouse actions, sharing a single text object for lightweight editing tasks, and running a modal event loop around an entire window rather than a single view object.
makeKeyWindow
or makeMainWindow
message. Setting the key and main windows programmatically is particularly useful when creating a new window. Because making a window key is often combined with ordering the window to the front of the screen, NSWindow defines a convenience method, makeKeyAndOrderFront:
, that performs both operations.
Not all windows are suitable for acting as the key or main window. For example, a window that merely displays information, and contains no objects that need to respond to events or action messages, can completely forgo ever becoming the key window. Similarly, a window that acts as a floating palette of items that are only dragged out by mouse actions never needs to be the key window. Such a window can be defined as a subclass of NSWindow that overrides the methods canBecomeKeyWindow
and canBecomeMainWindow
to return NO instead of the default of YES. Defining a window in this way prevents it from ever becoming the key or main window. Though NSWindow defines these methods, typically only subclasses of NSPanel refuse to accept key or main window status.
nextKeyView
outlets of views in the window and setting the window's initialFirstResponder
outlet to the view that you want selected when the window is first placed on screen. If you do not set this outlet, the window sets a key loop (not necessarily the same as the one you may have specified!) and picks a default initial first responder for you.
In addition to the key view loop, a window can have a default button cell, which uses the Return (or Enter) key as its key equivalent. The setDefaultButtonCell:
method establishes this button cell; you can also set it in Interface Builder by setting a button cell's key equivalent to `\r'. The default button cell draws itself as a focal element for keyboard interface control unless another button cell is focused on. In this case, it temporarily draws itself as normal and disables its key equivalent. Another default key established by NSWindow is the Escape key, which immediately aborts a modal loop (described below under "Modal Windows").
See the NSResponder class specification for more information on keyboard interface control.
fieldEditor:forObject:
method returns a window's field editor, after asking the delegate for a substitute using windowWillReturnFieldEditor:toObject:
. You can override the NSWindow method in subclasses or provide a delegate to substitute a class of text object different from the default of NSTextView, thereby customizing text editing in your application.
There are two mechanisms for operating a modal window or panel. The first, and simpler, is to invoke NSApplication's runModalForWindow:
method, which monopolizes events for the specified window until one of the NSApplication methods stopModal
, abortModal
, or stopModalWithCode:
is invoked, typically by a button's action method. The stopModal
method ends the modal status of the window or panel from within the event loop. It doesn't work if invoked from a method invoked by a timer or by a distributed object because those mechanisms operate outside of the event loop. To terminate the modal loop in these situations, you can use abortModal
. The stopModal
method is typically invoked when the user clicks the OK button (or equivalent), abortModal
when the user clicks the Cancel button (or presses the Escape key). These two methods are equivalent to stopModalWithCode:
with the appropriate argument. See the method descriptions in the NSApplication class specification for more information.
The second mechanism for operating a modal window or panel, called a modal session, allows the application to perform a long operation while it still sends events to the window or panel. Modal sessions are particularly useful for panels that allow the user to cancel or modify an operation. To begin a modal session, invoke NSApplication's beginModalSessionForWindow:
method, which sets the window up for the session and returns an identifier used for other session-controlling methods. At this point, the application can run in a loop that performs the operation, on each pass sending runModalSession:
to the application object so that pending events can be dispatched to the modal window. This method returns a code indicating whether the operation should continue, stop, or abort, which is typically established by the methods described above for runModalForWindow:
. After the loop concludes, you can remove the window from the screen and invoke NSApplication's endModalSession:
method to restore the normal event loop. The method description for runModalForWindow
in the NSApplication class specification includes sample code illustrating a modal session.
worksWhenModal
method to return YES. This allows the window to receive mouse and keyboard events even when a modal window is present. If a subclass needs to work when a modal window is present, it should usually be a subclass of NSPanel, not of NSWindow.
Modal windows and modal sessions provide different levels of control to the application and the user. Modal windows restrict all action to the window itself and any methods invoked from the window. Modal sessions allow the application to continue an operation while accepting input only through the modal session window. Beyond this, you can use distributed objects to perform background operations in a separate thread, while allowing the user to perform other actions with any part of the application. The background thread can communicate with the main thread, allowing the application to display the status of the operation in a nonmodal panel, perhaps including controls to stop or affect the operation as it occurs. Note that because the Application Kit isn't thread-safe, the background thread should communicate with a designated object in the main thread that in turn interacts with the Application Kit.
windowShouldClose:
, which requests approval to close, windowWillResize:toSize:
, which allows the delegate to constrain the NSWindow's size, windowWillUseStandardFrame:defaultFrame:
, which allows the delegate to set the window frame for zooming, and windowWillReturnFieldEditor:toObject
, which gives the delegate a chance to modify the field editor or substitute a different editor. See the individual notification and delegate method descriptions at the end of this specification for more information.
dragImage:at:offset:event:pasteboard:source:slideBack:
. An NSWindow can also serve as the destination for dragging operations, registering the types it accepts with registerForDraggedTypes:
and unregisterDraggedTypes
.NSView provides methods for adding, removing, discarding, and resetting cursor rectangles-areas where the cursor image changes when the mouse enters them. NSWindow overrides some of these methods and provides additional methods for working with cursor rectangles. For example, an NSWindow can:
disableCursorRects
and enableCursorRects
areCursorRectsEnabled
invalidateCursorRectsForView:
resetCursorRects
cacheImageInRect:
, restoreCachedImage
, and discardCachedImage
.contentRectForFrameRect:
(NSRect)frameRect styleMask:
(unsigned int)aStyle
Returns the content rectangle used by an NSWindow with a frame rectangle of frameRect and a style mask of aStyle. Both frameRect and the returned content rectangle are expressed in screen coordinates. See the initWithContentRect:styleMask:backing:defer:
method description for a list of style mask values.
See also:
+ frameRectForContentRect:styleMask:
defaultDepthLimit
Returns the default depth limit for instances of NSWindow. This is determined by the depth of the deepest screen level available to the window server.
The value returned can be examined with the Application Kit functions NSPlanarFromDepth
, NSColorSpaceFromDepth
, NSBitsPerSampleFromDepth
, NSBitsPerPixelFromDepth
.
See also:
- setDepthLimit:
, - setDynamicDepthLimit:
, - canStoreColor
frameRectForContentRect:
(NSRect)contentRect styleMask:
(unsigned int)aStyle
Returns the frame rectangle used by an NSWindow with a content rectangle of contentRect and a style mask of aStyle. Both contentRect and the returned frame rectangle are expressed in screen coordinates. See the initWithContentRect:styleMask:backing:defer:
method description for a list of style mask values.
See also:
+ contentRectForFrameRect:styleMask:
menuChanged:
(NSMenu *)aMenu
On Microsoft Windows, locates all objects inheriting from NSWindow that use aMenu and causes them to update their state and redisplay the menu. With other operating systems, this method does nothing.
See also:
- menu
(NSResponder)
minFrameWidthWithTitle:
(NSString *)aTitle styleMask:
(unsigned int)aStyle
Returns the minimum width that an NSWindow's frame rectangle must have for it to display all of aTitle, given aStyle as its style mask. See the initWithContentRect:styleMask:backing:defer:
method description for a list of acceptable style mask values.
removeFrameUsingName:
(NSString *)name
Removes the frame data stored under name from the application's user defaults.
See also:
- setFrameUsingName:
, - setFrameAutosaveName:
acceptsMouseMovedEvents
Returns YES if the receiver accepts and distributes mouse-moved events, NO if it doesn't. NSWindows by default don't accept mouse-moved events.
See also:
- setAcceptsMouseMovedEvents:
areCursorRectsEnabled
Returns YES if the receiver's cursor rectangles are enabled, NO if they're not.
See also:
- enableCursorRects
, - addCursorRect:cursor:
(NSView)
aspectRatio
Returns the receiver's size aspect ratio. The size of the receiver's frame rectangle is constrained to integral multiples of this ratio when the user resizes it. You can set an NSWindow's size to any ratio programmatically.
See also:
- resizeIncrements
, - setAspectRatio:
, - setFrame:display:
backgroundColor
Returns the color of the receiver's background.
See also:
- setBackgroundColor:
backingType
Returns the receiver's backing store type as one of the following constants:
NSBackingStoreBuffered
NSBackingStoreRetained
NSBackingStoreNonretained
See also:
- setBackingType:
becomeKeyWindow
Invoked automatically to inform the receiver that it has become the key window; never invoke this method directly. This method reestablishes the receiver's first responder, sends the becomeKeyWindow
message to that object if it responds, and posts an NSWindowDidBecomeKeyNotification to the default notification center.
See also:
- makeKeyWindow
, - makeKeyAndOrderFront:
, - becomeMainWindow
becomeMainWindow
Invoked automatically to inform the receiver that it has become the main window; never invoke this method directly. This method posts an NSWindowDidBecomeMainNotification to the default notification center.
See also:
- makeMainWindow
, - becomeKeyWindow
cacheImageInRect:
(NSRect)aRect
Stores the receiver's raster image from aRect, which is expressed in the receiver's base coordinate system. This allows the receiver 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.
See also:
- display
canBecomeKeyWindow
Returns YES if the receiver is able to be the key window, NO if it can't. Attempts to make the receiver the key window are abandoned if this method returns NO. NSWindow's implementation returns YES if the receiver has a title bar or a resize bar (size border in Windows), NO otherwise.
See also:
- isKeyWindow
, - makeKeyWindow
canBecomeMainWindow
Returns YES if the receiver is able to be the main window, NO if it can't. Attempts to make the receiver the main window are abandoned if this method returns NO. NSWindow's implementation returns YES if the receiver is visible, is not an NSPanel, and has a title bar or a resize mechanism. Otherwise it returns NO.
See also:
- isMainWindow
, - makeMainWindow
canStoreColor
Returns YES if the receiver has a depth limit that allows it to store color values, NO if it doesn't.
See also:
- depthLimit
, - shouldDrawColor
(NSView)
cascadeTopLeftFromPoint:
(NSPoint)topLeftPoint
Returns a point shifted from topLeftPoint that can be used to place the receiver in a cascade relative to another NSWindow positioned at topLeftPoint, so that the title bars of both NSWindows are fully visible. Both points are expressed in screen coordinates.
See also:
- setFrameTopLeftPoint:
center
Sets the receiver's location to the center of the screen: The receiver 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 receiver on screen, however; use makeKeyAndOrderFront:
to do that.
You typically use this method to place a NSWindow-most likely an attention panel-where the user can't miss it. This method is invoked automatically when an NSPanel is placed on the screen by NSApplication's runModalForWindow:
method.
close
Removes the receiver from the screen. If the receiver is set to be released when it's 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 to the default notification center.
The close
method differs in two important ways from the performClose:
method:
windowShouldClose:
message to the receiver or its delegate.
performClose:
if you need these features.
See also:
- orderOut:
constrainFrameRect:
(NSRect)frameRect toScreen:
(NSScreen *)aScreen
Modifies and returns frameRect so that its top edge lies on aScreen. If the receiver is resizable, the rectangle's height is adjusted to bring the bottom edge onto 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 receiver) whenever a titled NSWindow is placed on screen and whenever its size is changed.
Subclasses can override this method to prevent their instances from being constrained or to constrain them differently.
contentView
Returns the receivers's content view, the highest accessible NSView object in the receiver's view hierarchy.
See also:
- setContentView:
convertBaseToScreen:
(NSPoint)aPoint
Converts aPoint from the receiver's base coordinate system to the screen coordinate system. Returns the converted point.
See also:
- convertScreenToBase:
, - convertPoint:toView:
(NSView)
convertScreenToBase:
(NSPoint)aPoint
Converts aPoint from the screen coordinate system to the receiver's base coordinate system. Returns the converted point.
See also:
- convertBaseToScreen:
, - convertPoint:fromView:
(NSView)
currentEvent
Returns the event currently being processed by the application, by invoking NSApplication's currentEvent
method.
dataWithEPSInsideRect:
(NSRect)aRect
Returns EPS data that draws the region of the receiver within aRect (which is expressed in the receiver's base coordinate system). This data can be placed on a pasteboard, written to a file, or used to create an NSImage object.
See also:
- dataWithEPSInsideRect:
(NSView), - writeEPSInsideRect:toPasteboard:
(NSView)
deepestScreen
Returns the deepest screen that the receiver is on (it may be split over several screens), or nil
if the receiver is off screen.
See also:
- screen
defaultButtonCell
Returns the button cell that performs as if clicked when the NSWindow receives a Return (or Enter) key event. 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.
See also:
- setDefaultButtonCell:
, - disableKeyEquivalentForDefaultButtonCell
,
- enableKeyEquivalentForDefaultButtonCell
delegate
Returns the receiver's delegate, or returns nil
if it doesn't have one.
See also:
- setDelegate:
deminiaturize:
(id)sender
Deminiaturizes the receiver. You rarely need to invoke this method; it's invoked automatically when an NSWindow is deminiaturized by the user.
See also:
- miniaturize:
, - styleMask
depthLimit
Returns the depth limit of the receiver. The value returned can be examined with the Application Kit functions NSPlanarFromDepth
, NSColorSpaceFromDepth
, NSBitsPerSampleFromDepth
, NSBitsPerPixelFromDepth
.
See also:
+ defaultDepthLimit
, - setDepthLimit:
, - setDynamicDepthLimit:
deviceDescription
Returns a dictionary containing information about the receiver's resolution, color depth, and so on. This information is useful for tuning images and colors to the window's display capabilities. The contents of the dictionary are:
Dictionary Key | Value |
---|---|
NSDeviceResolution | An NSValue containing a value of type NSSize that describe the receiver's raster resolution in dots per inch (dpi). |
NSDeviceColorSpaceName | An NSString giving the name of the receiver's color space. See the Application Kit Types and Constants for a list of possible values. |
NSDeviceBitsPerSample | An NSNumber containing an integer that gives the bit depth of the receiver's raster image (2-bit, 8-bit, and so forth). |
NSDeviceIsScreen | YES, indicating that the receiver displays on the screen. |
NSDeviceSize | An NSValue containing a value of type NSSize that gives the size of the receiver's frame rectangle. |
See also:
- deviceDescription
(NSScreen), - bestRepresentationForDevice:
(NSImage),
- colorUsingColorSpaceName:
(NSColor)
disableCursorRects
Disables all cursor rectangle management within the receiver. Use this method when you need to do some special cursor manipulation and you don't want the Application Kit interfering.
See also:
- enableCursorRects
disableFlushWindow
Disables the flushWindow
method for the receiver. If the receiver is buffered, disabling flushWindow
prevents drawing from being automatically flushed by NSView's display...
methods from the receiver's backing store to the screen. This permits several NSViews to be drawn before the results are shown to the user.
Flushing should be disabled only temporarily, while the NSWindow'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.
disableKeyEquivalentForDefaultButtonCell
Disables the default button cell's key equivalent, so that it doesn't perform a click when the user presses Return (or Enter). See the method description for defaultButtonCell
for more information.
See also:
- enableKeyEquivalentForDefaultButtonCell
discardCachedImage
Discards all of the receiver's cached image rectangles. An NSWindow automatically discards its cached image rectangles when it displays.
See also:
- cacheImageInRect:
, - restoreCachedImage
, - display
discardCursorRects
Invalidates all cursor rectangles in the receiver. 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 might want to override it to change its behavior.
discardEventsMatchingMask:
(unsigned int)mask beforeEvent:
(NSEvent *)lastEvent
Forwards the message to the NSApplication object, which handles it as described in the NSApplication class specification.
display
Passes a display
message down the receiver's view hierarchy, thus redrawing all NSViews within the receiver, including the frame view which draws the border, title bar, and other peripheral elements.
You rarely need to invoke this method. NSWindows normally record which of their NSViews need display and display them automatically on each pass through the event loop.
See also:
- display
(NSView), - displayIfNeeded
, - isAutodisplay
displayIfNeeded
Passes a display
IfNeeded
message down the receiver's view hierarchy, thus redrawing all NSViews that need to be displayed, including the frame view which draws the border, title bar, and other peripheral elements. This method is useful when you want to modify some number of NSViews and then display only the ones that were modified.
You rarely need to invoke this method. NSWindows normally record which of their NSViews need display and display them automatically on each pass through the event loop.
See also:
- display
, - displayIfNeeded
(NSView), - setNeedsDisplay:
(NSView), - isAutodisplay
dragImage:
(NSImage *)anImageat:
(NSPoint)aPointoffset:
(NSSize)initialOffsetevent:
(NSEvent *)theEventpasteboard:
(NSPasteboard *)pboardsource:
(id)sourceObjectslideBack:
(BOOL)flag
Begins a dragging session. This method should be invoked only from within a view's implementation of the mouseDown:
method (which overrides the version defined in NSResponder). Essentially the same as NSView's method of the same name, except that aPoint is given in the NSWindow's base coordinate system. See the description of this method in the NSView class specification for more information.
enableCursorRects
Reenables cursor rectangle management within the receiver after a disableCursorRects
message.
enableFlushWindow
Reenables the flushWindow
method for the receiver after it was disabled through a previous disableFlushWindow
message.
enableKeyEquivalentForDefaultButtonCell
Reenables the default button cell's key equivalent, so that it performs a click when the user presses Return (or Enter). See the method description for defaultButtonCell
for more information.
See also:
- disableKeyEquivalentForDefaultButtonCell
endEditingFor:
(id)anObject
Forces the field editor, which anObject is assumed to be using, to give up its first responder status, and prepares it for its next assignment. If the field editor is the first responder, it's made to resign that status even if its resignFirstResponder
method returns NO. This 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 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];
}
See also:
- fieldEditor:forObject:
, - windowWillReturnFieldEditor:toObject:
fax:
(id)sender
Runs the Fax panel, and if the user chooses an option other than canceling, prints the receiver (its frame view and all subviews) to a fax modem.
See also:
- print:
fieldEditor:
(BOOL)createFlag forObject:
(id)anObject
Returns the receiver's field editor, creating it if needed and if createFlag is YES. Returns nil
if createFlag is NO and the field editor doesn't exist. anObject is used to allow the receiver's delegate to substitute another object in place of the field editor, as described below. 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 field editor is provided as a convenience and 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 NSText object).
A freshly created NSWindow doesn't have a field editor. After a field editor has been created for an NSWindow, the createFlag argument is ignored. By passing NO for createFlag and testing the return value, however, you can predicate an action on the existence of the field editor.
The receiver's delegate can substitute a custom editor in place of the NSWindow's field editor by implementing windowWillReturnFieldEditor:toObject:
. The receiver sends this message to its delegate with itself and anObject as the arguments, and if the return value is not nil
the NSWindow returns that object instead of its field editor. However, note the following:
windowWillReturnFieldEditor:toObject:
isn't sent.
firstResponder
Returns the receiver's first responder.
See also:
- makeFirstResponder:
, - acceptsFirstResponder
(NSResponder)
flushWindow
Flushes the receiver's off-screen buffer to the screen if the receiver is buffered and flushing is enabled. Does nothing for other display devices, such as a printer. This method is automatically invoked by NSWindow's and NSView's display
and displayIfNeeded
methods.
See also:
- flushWindowIfNeeded
, - disableFlushWindow
, - enableFlushWindow
flushWindowIfNeeded
Flushes the receiver's off-screen buffer to the screen if flushing is enabled and if the last flushWindow
message had no effect because flushing was disabled. To avoid unnecessary flushing, use this method rather than flushWindow
to flush an NSWindow after flushing has been reenabled.
See also:
- flushWindow
, - disableFlushWindow
, - enableFlushWindow
frame
Returns the receiver's frame rectangle. The frame rectangle is always reckoned in the screen coordinate system.
See also:
- screen
, - deepestScreen
frameAutosaveName
Returns the name used to automatically save the receiver's frame rectangle data in the defaults system, as set through setFrameAutosaveName:
. If the receiver has an autosave name, its frame data is written whenever the frame rectangle changes.
See also:
- setFrameUsingName:
gState
Returns the PostScript graphics state object associated with the receiver. This graphics state is used by default for all NSViews in the receiver's view hierarchy, but individual NSViews can be made to use their own with the NSView method allocateGState
.
hasDynamicDepthLimit
Returns YES if the receiver's depth limit can change to match the depth of the screen it's on, NO if it can't.
See also:
- setDynamicDepthLimit:
hidesOnDeactivate
Returns YES if the receiver is removed from the screen when its application is deactivated, NO if it remains on screen.
See also:
- setHidesOnDeactivate:
initialFirstResponder
Returns the NSView that's made first responder the first time the receiver is placed on screen.
See also:
- setInitialFirstResponder:
, - setNextKeyView:
(NSView)
initWithContentRect:
(NSRect)contentRectstyleMask:
(unsigned int)styleMaskbacking:
(NSBackingStoreType)backingTypedefer:
(BOOL)flag
Initializes the receiver, a newly allocated NSWindow object, and returns self
. This method is the designated initializer for the NSWindow class.
contentRect specifies the location and size of the NSWindow's content area in screen coordinates. Note that the Window Server limits window position coordinates to ±16,000 and sizes to 10,000.
styleMask specifies the receiver's style. It can either be NSBorderlessWindowMask, or it can contain any of the following options, combined using the C bitwise OR operator:
Option | Meaning |
---|---|
NSTitledWindowMask | The NSWindow displays a title bar. |
NSClosableWindowMask | The NSWindow displays a close button. |
NSMiniaturizableWindowMask | The NSWindow displays a miniaturize button. |
NSResizableWindowMask | The NSWindow displays a resize bar or border. |
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 an NSWindow's style mask should include NSTitledWindowMask if it includes any of the others.
backingType specifies how the drawing done in the receiver is buffered by the object's window device:
NSBackingStoreBuffered
NSBackingStoreRetained
NSBackingStoreNonretained
flag determines whether the Window Server creates a window device for the new object immediately. If flag is YES, it defers creating the window until the receiver is moved on screen. All display messages sent to the NSWindow or its NSViews are postponed until the window is created, just before it's moved on screen. Deferring the creation of the window improves launch time and minimizes the virtual memory load on the Window Server.
The new NSWindow creates an instance of NSView to be its default content view. You can replace it with your own object by using the setContentView:
method.
See also:
- orderFront:
, - setTitle:
, - setOneShot:
, - initWithContentRect:styleMask:backing:defer:
screen:
initWithContentRect:
(NSRect)contentRectstyleMask:
(unsigned int)styleMaskbacking:
(NSBackingStoreType)bufferingTypedefer:
(BOOL)flagscreen:
(NSScreen *)aScreen
Initializes a newly allocated NSWindow object and returns self
. This method is equivalent to initWithContentRect:styleMask:backing:defer:
, except that the content rectangle is specified relative to the lower-left corner of aScreen.
If aScreen is nil
, the content rectangle is interpreted relative to the lower-left corner of the main screen. 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.
See also:
- orderFront:
, - setTitle:
, - setOneShot:
interfaceStyle
Returns the receiver's interface style, such as NSMacintoshInterfaceStyle or NSWindows95InterfaceStyle. A responder's style (if other than NSNoInterfaceStyle) overrides all other settings, such as those established by the defaults system.
See also:
- setInterfaceStyle:
invalidateCursorRectsForView:
(NSView *)aView
Marks as invalid the cursor rectangles of aView, an NSView in the receiver's view hierarchy, so that they'll be set up again when the receiver becomes key (or immediately if the receiver is key).
See also:
- resetCursorRects
, - resetCursorRects
(NSView)
isAutodisplay
Returns YES if the receiver automatically displays its views that are marked as needing it, NO if it doesn't. Automatic display typically occurs on each pass through the event loop.
See also:
- setAutodisplay:
, - displayIfNeeded
, - setNeedsDisplay:
(NSView)
isDocumentEdited
Returns YES or NO according to the argument supplied with the last setDocumentEdited:
message.
isExcludedFromWindowsMenu
Returns YES if the receiver's title is omitted from the application's Windows menu, NO if it is listed.
See also:
- setExcludedFromWindowsMenu:
isFlushWindowDisabled
Returns YES if the receiver's flushing ability has been disabled; otherwise returns NO.
See also:
- disableFlushWindow
, - enableFlushWindow
isKeyWindow
Returns YES if the receiver is the key window for the application, NO if it isn't.
See also:
- isMainWindow
, - makeKeyWindow
isMainWindow
Returns YES if the receiver is the main window for the application, NO if it isn't.
See also:
- isKeyWindow
, - makeMainWindow
isMiniaturized
Returns YES if the receiver has been miniaturized, NO if it hasn't. A miniaturized window is removed from the screen and replaced by a miniwindow, icon, or button that represents it, called the counterpart (the particular form depends on the platform).
See also:
- miniaturize:
isOneShot
Returns YES if the PostScript window device that the receiver manages is freed when it's removed from the screen list, NO if not. The default is NO.
See also:
- setOneShot:
isReleasedWhenClosed
Returns YES if the receiver is automatically released after being closed, NO if it's simply removed from the screen. The default for NSWindow is YES; the default for NSPanel is NO.
See also:
- setReleasedWhenClosed:
isVisible
Returns YES if the receiver is on screen (even if it's obscured by other windows).
See also:
- visibleRect
(NSView)
keyDown:
(NSEvent *)theEvent
Handles a keyboard event that may need to be interpreted as changing the key view or triggering a mnemonic.
See also:
- selectNextKeyView:
, - nextKeyView
(NSView), - performMnemonic:
(NSView)
keyViewSelectionDirection
Returns the direction that the receiver is currently using to change the key view, one of:
Value | Meaning |
---|---|
NSDirectSelection | The receiver isn't traversing the key view loop. |
NSSelectingNext | The receiver is proceeding to the next valid key view. |
NSSelectingPrevious | The receiver is proceeding to the previous valid key view. |
See also:
- selectNextKeyView:
, - selectPreviousKeyView:
level
Returns the level of the receiver as set using setLevel:
. See that method description for a list of possible values.
makeFirstResponder:
(NSResponder *)aResponder
Attempts to make aResponder the first responder for the receiver. If aResponder isn't already the first responder, this method first sends a resignFirstResponder
message to the object that is. If that object refuses to resign, it remains the first responder and this method immediately returns NO. If it returns YES, this methods sends a becomeFirstResponder
message to aResponder. If aResponder accepts first responder status, this method returns YES. If it refuses, this method returns NO, and the NSWindow becomes first responder.
The Application Kit 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. aResponder is typically an NSView in the receiver's view hierarchy.
See also:
- becomeFirstResponder
(NSResponder), - resignFirstResponder
(NSResponder)
makeKeyAndOrderFront:
(id)sender
Moves the receiver to the front of the screen list, within its level, and makes it the key window.
See also:
- orderFront:
, - orderBack:
, - orderOut:
, - orderWindow:relativeTo:
, - setLevel:
makeKeyWindow
Makes the receiver the key window.
See also:
- makeMainWindow
, - becomeKeyWindow
, - isKeyWindow
makeMainWindow
Makes the receiver the main window.
See also:
- makeKeyWindow
, - becomeMainWindow
, - isMainWindow
maxSize
Returns the maximum size to which the receiver's frame can be sized either by the user or by the setFrame...
methods other than setFrame:display:
.
See also:
- setMaxSize:
, - minSize
, - aspectRatio
, - resizeIncrements
miniaturize:
(id)sender
Removes the receiver from the screen list and displays its counterpart in the appropriate location.
See also:
- deminiaturize:
miniwindowImage
Returns the image that's displayed in the receiver's miniwindow.
See also:
- setMiniwindowImage:
, - miniwindowTitle
miniwindowTitle
Returns the title that's displayed in the receiver's miniwindow.
See also:
- setMiniwindowTitle:
, - miniwindowImage
minSize
Returns the minimum size to which the receiver's frame can be sized either by the user or by the setFrame...
methods other than setFrame:display:
.
See also:
- setMinSize:
, - maxSize
, - aspectRatio
, - resizeIncrements
mouseLocationOutsideOfEventStream
Returns the current location of the mouse reckoned in the receiver's base coordinate system, regardless of the current event being handled or of any events pending.
See also:
- currentEvent
(NSApplication)
nextEventMatchingMask:
(unsigned int)mask
Invokes NSApplication's nextEventMatchingMask:untilDate:inMode:dequeue:
method, using mask as the first argument, with an unlimited expiration, a mode of NSEventTrackingRunLoopMode, and a dequeue flag of YES. See the method description in the NSApplication class specification for more information.
nextEventMatchingMask:
(unsigned int)maskuntilDate:
(NSDate *)expirationDateinMode:
(NSString *)modedequeue:
(BOOL)flag
Forwards the message to the global NSApplication object, NSApp. See the method description in the NSApplication class specification for more information.
orderBack:
(id)sender
Moves the receiver to the back of its level in the screen list, without changing either the key window or the main window.
See also:
- orderFront:
, - orderOut:
, - orderWindow:relativeTo:
, - makeKeyAndOrderFront:
,
- level
orderFront:
(id)sender
Moves the receiver to the front of its level in the screen list, without changing either the key window or the main window.
See also:
- orderBack:
, - orderOut:
, - orderWindow:relativeTo:
, - makeKeyAndOrderFront:
, - level
orderFrontRegardless
Moves the receiver to the front of its level, even if its application isn't active, but without changing either the key window or the main window. Normally an NSWindow can't be moved in front of the key window unless the NSWindow 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.
See also:
- orderFront:
, - level
orderOut:
(id)sender
Takes the receiver out of the screen list. If the receiver is the key or main window, the NSWindow immediately behind it is made key or main in its place. Calling the orderOut:
method causes the receiver 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.
See also:
- orderFront:
, - orderBack:
, - orderWindow:relativeTo:
,
- setReleasedWhenClosed:
orderWindow:
(NSWindowOrderingMode)place relativeTo:
(int)otherWindowNumber
Repositions the receiver's window device in the Window Server's screen list. If place is NSWindowOut, the receiver is removed from the screen list and otherWindowNumber is ignored. If it's NSWindowAbove the receiver is ordered immediately in front of the window whose window number is otherWindowNumber. Similarly, if place is NSWindowBelow, the receiver is placed immediately behind the window represented by otherWindowNumber. If otherWindowNumber is 0, the receiver is placed in front of or behind all other windows in its level.
See also:
- orderFront:
, - orderBack:
, - orderOut:
, - makeKeyAndOrderFront:
, - level
,
- windowNumber
performClose:
(id)sender
Simulates the user clicking the close button by momentarily highlighting the button and then closing the window. If the receiver's delegate or the receiver itself implements windowShouldClose:
, then that message is sent with the receiver as the argument. (Only one such message is sent; if both the delegate and the NSWindow 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 receiver doesn't have a close button or can't be closed (for example, if the delegate replies NO to a windowShouldClose:
message), then this method calls the NSBeep
function.
See also:
- styleMask
, - performClick:
(NSButton), - performMiniaturize:
performMiniaturize:
(id)sender
Simulates the user clicking the miniaturize button by momentarily highlighting the button then miniaturizing the window. If the receiver doesn't have a miniaturize button or can't be miniaturized for some reason, this method calls the NSBeep
function.
See also:
- close
, - styleMask
, - performClick:
(NSButton), - performClose:
performZoom:
(id)sender
Simulates the user clicking the zoom box by momentarily highlighting the button and then zooming the window. If the receiver doesn't have a zoom box or can't be zoomed for some reason, this method calls the NSBeep
function.
See also:
- styleMask
, - performClick:
(NSButton), - zoom:
postEvent:
(NSEvent *)anEvent atStart:
(BOOL)flag
Forwards the message to the global NSApplication object, NSApp.
print:
(id)sender
Runs the Print panel, and if the user chooses an option other than canceling, prints the receiver (its frame view and all subviews).
See also:
- fax:
registerForDraggedTypes:
(NSArray *)pboardTypes
Registers pboardTypes as the pasteboard types that the receiver will accept as the destination of an image-dragging session.
See also:
- unregisterDraggedTypes
representedFilename
Returns the name of the file that the receiver represents.
See also:
- setRepresentedFilename:
resetCursorRects
Invokes discardCursorRects
to clear the receiver's cursor rectangles, then sends resetCursorRects
to every NSView in the receiver'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:
.
resignKeyWindow
Never invoke this method; it's invoked automatically when the NSWindow resigns key window status. This method sends resignKeyWindow
to the receiver's first responder, sends windowDidResignKey:
to the receiver's delegate, and posts an NSWindowDidResignKeyNotification to the default notification center.
See also:
- becomeKeyWindow
, - resignMainWindow
resignMainWindow
Never invoke this method; it's invoked automatically when the NSWindow resigns main window status. This method sends windowDidResignMain:
to the receiver's delegate and posts an NSWindowDidResignMainNotification to the default notification center.
See also:
- becomeMainWindow
, - resignKeyWindow
resizeFlags
Valid only while the receiver is being resized, this method returns the flags field of the event record for the mouse-down event that initiated the resizing session. The integer encodes, as a mask, which of the modifier keys was held down when the event occurred. The flags are listed in the NSEvent class's modifierFlags
method description. 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:
.
resizeIncrements
Returns the receiver's resizing increments, which restrict the user's ability to resize it so that its width and height alter by integral multiples of increments.width and increments.height when the user resizes it. These amounts are whole number values, 1.0 or greater. You can set an NSWindow's size to any value programmatically.
See also:
- setResizeIncrements:
, - setAspectRatio:
, - setFrame:display:
restoreCachedImage
Splices the receiver'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:
. You must invoke flushWindowIfNeeded
after this method to guarantee proper redisplay. An NSWindow automatically discards its cached image rectangles when it displays.
See also:
- discardCachedImage
, - display
saveFrameUsingName:
(NSString *)name
Saves the receiver's frame rectangle in the user defaults system. With the companion method setFrameUsingName:
, you can save and reset an NSWindow's frame over various launchings of an application. The default is owned by the application and stored under the name "NSWindow Frame name". See the NSUserDefaults class specification for more information.
See also:
- stringWithSavedFrame
screen
Returns the screen that the receiver is on. If the receiver is partly on one screen and partly on another, the screen where most of it lies is the one returned.
See also:
- deepestScreen
selectKeyViewFollowingView:
(NSView *)aView
Sends the NSView message nextValidKeyView:
to aView, and if that message returns an NSView, invokes makeFirstResponder:
with the returned NSView.
See also:
- selectKeyViewPrecedingView:
selectKeyViewPrecedingView:
(NSView *)aView
Sends the NSView message previousValidKeyView:
to aView, and if that message returns an NSView, invokes makeFirstResponder:
with the returned NSView.
See also:
- selectKeyViewFollowingView:
selectNextKeyView:
(id)sender
Searches for a candidate key view and, if it finds one, invokes makeFirstResponder:
to establish it as the first responder. The candidate is one of the following (searched for in this order):
nextValidKeyView:
method.
setInitialFirstResponder:
) if it returns YES to an acceptsFirstResponder
message.
nil
.
- selectPreviousKeyView:
, - selectKeyViewFollowingView:
selectPreviousKeyView:
(id)sender
Searches for a candidate key view and, if it finds one, invokes makeFirstResponder:
to establish it as the first responder. The candidate is one of the following (searched for in this order):
previousValidKeyView:
method.
setInitialFirstResponder:
) if it returns YES to an acceptsFirstResponder
message.
nil
.
- selectNextKeyView:
, - selectKeyViewPrecedingView:
sendEvent:
(NSEvent *)theEvent
Dispatches mouse and keyboard events sent to the receiver by the NSApplication object. Never invoke this method directly.
setAcceptsMouseMovedEvents:
(BOOL)flag
Sets whether the receiver accepts mouse-moved events and distributes them to its responders. If flag is YES it does accept them; if flag is NO it doesn't. NSWindows by default don't accept mouse-moved events.
See also:
- acceptsMouseMovedEvents
setAspectRatio:
(NSSize)ratio
Sets the receiver's size aspect ratio to ratio, constraining the size of its frame rectangle to integral multiples of this size when the user resizes it.
An NSWindow'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, you send the NSWindow object a setResizeIncrements:
message with the width and height set to 1.0:
[myWindow setResizeIncrements:NSMakeSize(1.0,1.0)];
See also:
- aspectRatio
, - setFrame:display:
setAutodisplay:
(BOOL)flag
Sets whether the receiver automatically displays its views that are marked as needing it. If flag is YES, views are automatically displayed as needed, typically on each pass through the event loop. If flag is NO, the receiver or its views must be explicitly displayed.
See also:
- isAutodisplay
, - displayIfNeeded
, - displayIfNeeded
(NSView)
setBackgroundColor:
(NSColor *)aColor
Sets the color of the receiver's background to aColor.
See also:
- backgroundColor
setBackingType:
(NSBackingStoreType)backingType
Sets the receiver's backing store type to backingType, which may be one of the following constants:
NSBackingStoreBuffered
NSBackingStoreRetained
This method can only be used to switch a buffered NSWindow to retained or vice versa; you can't change the backing type to or from nonretained after initializing an NSWindow (a PostScript error is generated if you attempt to do so).
See also:
- backingType
setContentSize:
(NSSize)aSize
Sets the size of the receiver's content view to aSize, which is expressed in the receiver's base coordinate system. This in turn alters the size of the NSWindow itself. Note that the Window Server limits window sizes to 10,000; if necessary, be sure to limit aSize relative to the frame rectangle.
See also:
- setFrame:display:
, + contentRectForFrameRect:styleMask:
,
+ frameRectForContentRect:styleMask:
setContentView:
(NSView *)aView
Makes aView the receiver's content view; the previous content view is removed from the receiver's view hierarchy and released. aView is resized to fit precisely within the content area of the NSWindow. 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 or NSView.
See also:
- contentView
, - setContentSize:
setDefaultButtonCell:
(NSButtonCell *)aButtonCell
Makes the key equivalent of aButtonCell's the Return (or Enter) key, so that when the user presses Return that button performs as if clicked. See the method description for defaultButtonCell
for more information.
See also:
- disableKeyEquivalentForDefaultButtonCell
,
- enableKeyEquivalentForDefaultButtonCell
setDelegate:
(id)anObject
Makes anObject the receiver's delegate, without retaining it. An NSWindow's delegate is inserted in the responder chain after the NSWindow itself and is informed of various actions by the NSWindow through delegation messages.
See also:
- delegate
, - tryToPerform:with:
, - sendAction:to:from:
(NSApplication)
setDepthLimit:
(NSWindowDepth)limit
Sets the depth limit of the receiver to limit, which can be determined using the NSBestDepth
function. Passing a value of 0 for limit sets the depth limit to the receiver's default depth limit; using a value of 0 can be useful for reverting an NSWindow to its initial depth.
See also:
- depthLimit
, + defaultDepthLimit
, - setDynamicDepthLimit:
setDocumentEdited:
(BOOL)flag
Sets whether the receiver's document has been edited and not saved. NSWindows are by default in "not edited" status.
You should invoke this method with an argument of YES every time the NSWindow's document changes in such a way that it needs to be saved and with an argument of NO every time it gets saved. Then, before closing the NSWindow you can use isDocumentEdited
to determine whether to allow the user a chance to save the document.
setDynamicDepthLimit:
(BOOL)flag
Sets whether the receiver changes its depth to match the depth of the screen that it's on, or the depth of the deepest screen when it spans multiple screens. If flag is YES, the depth limit depends on which screen the receiver is on. If flag is NO, the receiver uses either its preset depth limit or the default depth limit. A different, and nondynamic, depth limit can be set with the setDepthLimit:
method.
See also:
- hasDynamicDepthLimit
, + defaultDepthLimit
setExcludedFromWindowsMenu:
(BOOL)flag
Sets whether the receiver's title is omitted from the application's Windows menu. If flag is YES it's omitted; if flag is NO, it's listed when it or its miniwindow is on screen. The default is NO.
See also:
- isExcludedFromWindowsMenu
setFrame:
(NSRect)frameRect display:
(BOOL)flag
Sets the origin and size of the receiver's frame rectangle according to frameRect, thereby setting its position and size on screen, and invokes display
if flag is YES. Note that the Window Server limits window position coordinates to ±16,000 and sizes to 10,000.
See also:
- frame
, - setFrameFromString:
, - setFrameOrigin:
, - setFrameTopLeftPoint:
,
- setFrameUsingName:
setFrameAutosaveName:
(NSString *)name
Sets the name used to automatically save the receiver's frame rectangle in the defaults system to name. If name isn't the empty string (@""), the receiver's frame is saved as a user default (as described in saveFrameUsingName:
) each time the frame changes. Returns YES if the name is set successfully, NO if it's being used as an autosave name by another NSWindow in the application (in which case the receiver's old name remains in effect).
See also:
+ removeFrameUsingName:
, - stringWithSavedFrame
, - setFrameFromString:
setFrameFromString:
(NSString *)aString
Sets the receiver's frame rectangle from the string representation aString, a representation previously creating using stringWithSavedFrame
. The frame is constrained according to the receiver's minimum and maximum size settings. This method causes a windowWillResize:toSize:
message to be sent to the delegate.
setFrameOrigin:
(NSPoint)aPoint
Positions the lower-left corner of the receiver's frame rectangle at aPoint in screen coordinates. Note that the Window Server limits window position coordinates to ±16,000.
See also:
- setFrame:display:
, - setFrameTopLeftPoint:
setFrameTopLeftPoint:
(NSPoint)aPoint
Positions the top-left corner of the receiver's frame rectangle at aPoint in screen coordinates. 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.
See also:
- cascadeTopLeftFromPoint:
, - setFrame:display:
, - setFrameOrigin:
setFrameUsingName:
(NSString *)name
Sets the receiver's frame rectangle by reading the rectangle data stored in name from the defaults system. The frame is constrained according to the receiver's minimum and maximum size settings. This method causes a windowWillResize:toSize:
message to be sent to the delegate. Returns YES if name is read and the frame is set successfully; otherwise returns NO.
See also:
- setFrameAutosaveName:
, + removeFrameUsingName:
, - stringWithSavedFrame
,
- setFrameFromString:
setHidesOnDeactivate:
(BOOL)flag
Sets whether the receiver is removed from the screen when the application is inactive. If flag is YES, the receiver is hidden (taken out of the screen list) when the application stops being the active application. If flag is NO, the receiver stays on screen. The default for NSWindow is NO; the default for NSPanel is YES.
See also:
- hidesOnDeactivate
setInitialFirstResponder:
(NSView *)aView
Sets aView as the NSView that's made first responder (also called the key view) the first time the receiver is placed on screen.
See also:
- initialFirstResponder
setInterfaceStyle:(
NSInterfaceStyle)
interfaceStyle
Sets the receiver's style to the style specified by interfaceStyle, such as NSMacintoshInterfaceStyle or NSWindows95InterfaceStyle. You should almost never need to invoke or override this method, but if you do override it, your version should always invoke super
.
See also:
- interfaceStyle
setLevel:
(int)newLevel
Sets the receiver's window level to newLevel. Some useful predefined values are:
Level | Comment |
---|---|
NSNormalWindowLevel | The default level for NSWindow objects. |
NSFloatingWindowLevel | Useful for floating palettes. |
NSDockWindowLevel | Reserved for the application dock (Mach-based systems only). |
NSSubmenuWindowLevel | Reserved for submenus (not used on Microsoft Windows). Synonymous with NSTornOffMenuWindowLevel. |
NSTornOffMenuWindowLevel | The level for a torn-off menu. Synonymous with NSSubmenuWindowLevel. |
NSMainMenuWindowLevel | Reserved for the application's main menu (not used on Microsoft Windows). |
NSModalPanelWindowLevel | The level for a modal panel. |
NSPopUpMenuWindowLevel | The level for a popup menu. |
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 of its peers in that level.
The constant NSTornOffMenuWindowLevel is preferable to its synonym, NSSubmenuWindowLevel
See also:
- level
, - orderWindow:relativeTo:
, - orderFront:
, - orderBack:
setMaxSize:
(NSSize)aSize
Sets the maximum size to which the receiver's frame can be sized to aSize. 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.
See also:
- maxSize
, - setMinSize:
, - setAspectRatio:
, - setResizeIncrements:
setMiniwindowImage:
(NSImage *)anImage
Sets the image displayed by the receiver's miniwindow to anImage.
See also:
- miniwindowImage
, - isMiniaturized
setMiniwindowTitle:
(NSString *)aString
Sets the title of the receiver's miniaturized counterpart to aString and redisplays it. A miniwindow's title normally reflects that of its full-size counterpart, abbreviated to fit if necessary. Although this method allows you to set the miniwindow's title explicitly, changing the full-size NSWindow's title (through setTitle:
or setTitleWithRepresentedFilename:
) automatically changes the miniwindow's title as well.
See also:
- miniwindowTitle
setMinSize:
(NSSize)aSize
Returns the minimum size to which the receiver's frame can be sized to aSize. The minimum size constraint is enforced for resizing by the user as well as for the setFrame...
methods other than setFrame:display:
.
See also:
- minSize
, - setMaxSize:
, - setAspectRatio:
, - setResizeIncrements:
setOneShot:
(BOOL)flag
Sets whether the PostScript window device that the receiver manages should be freed when it's removed from the screen list (and another one created if it's returned to the screen). Freeing the window device when it's removed from the screen list can result in memory savings and performance improvement for NSWindows that don't take long to display. It's particularly appropriate for NSWindows that the user might use once or twice but not display continually. The default is NO.
See also:
- isOneShot
setReleasedWhenClosed:
(BOOL)flag
Sets whether the receiver is merely hidden (NO) or hidden and then released (YES) when it receives a close
message. The default for NSWindow is YES; the default for NSPanel is NO.
Another strategy for releasing an NSWindow is to have its delegate autorelease it on receiving a windowShouldClose:
message.
See also:
- close
, - isReleasedWhenClosed
setRepresentedFilename:
(NSString *)path
Sets the name of the file that the receiver represents to path.
See also:
- representedFilename
, - setTitleWithRepresentedFilename:
setResizeIncrements:
(NSSize)increments
Restricts the user's ability to resize the window so that the width and height change by multiples of increments.width and increments.height as the user resizes the window. The width and height increments should be whole numbers, 1.0 or greater. Whatever the current resize increments, you can set an NSWindow's size to any height and width programmatically.
Resize increments and aspect ratio are mutually exclusive attributes. For more information, see setAspectRatio:
.
See also:
- resizeIncrements
, - setFrame:display:
setTitle:
(NSString *)aString
Sets the string that appears in the receiver's title bar (if it has one) to aString and displays the title. Also sets the title of the receiver's miniwindow.
See also:
- title
, - setTitleWithRepresentedFilename:
, - setMiniwindowTitle:
setTitleWithRepresentedFilename:
(NSString *)path
Sets path as the receiver's title, formatting it as a file system path, and records path as the receiver's associated filename using setRepresentedFilename:
. The title format varies with the platform. On Mach-based systems, the filename is displayed first, followed by an em dash and the path for the directory containing the file. The em dash is offset by two spaces on either side. For example:
MyFile - /Net/server/group/home
This method also sets the title of the receiver's miniwindow.
See also:
- title
, - setTitle:
, - setMiniwindowTitle:
setViewsNeedDisplay:
(BOOL)flag
Sets whether the receiver's views need display (YES) or do not need display (NO). You should rarely need to invoke this method; NSView's setNeedsDisplay:
and similar methods invoke it automatically.
See also:
- viewsNeedDisplay
stringWithSavedFrame
Returns a string that represents the receiver's frame rectangle in a format that can be used with a later setFrameUsingName:
message.
styleMask
Returns the receiver's style mask, indicating what kinds of control items it displays. See the information about the style mask in the initWithContentRect:styleMask:backing:defer:
method description. An NSWindow's style is set when the object is initialized. Once set, it can't be changed.
title
Returns the string that appears in the title bar of the receiver.
See also:
- setTitle:
, - setTitleWithRepresentedFilename:
tryToPerform:
(SEL)anAction with:
(id)anObject
Dispatches action messages. The receiver tries to perform the method anAction using its inherited NSResponder method tryToPerform:with:
. If the receiver doesn't perform anAction, the delegate is given the opportunity to perform it using its inherited NSObject method performSelector:withObject:
. If either the receiver or its delegate accepts anAction, this method returns YES; otherwise it returns NO.
unregisterDraggedTypes
Unregisters the receiver as a possible destination for dragging operations.
See also:
- registerForDraggedTypes:
update
The default implementation of this method does nothing more than post an NSWindowDidUpdateNotification to the default notification center. A subclass can override this method to perform specialized operations, but should send an update
message to super
just before returning. For example, the NSMenu class implements this method to disable and enable menu commands.
An NSWindow is automatically sent an update
message on every pass through the event loop and before it's displayed on screen. You can manually cause an update message to be sent to all visible NSWindows through NSApplication's updateWindows
method.
See also:
- setWindowsNeedUpdate:
(NSApplication), - updateWindows
(NSApplication)
useOptimizedDrawing:
(BOOL)flag
Informs the receiver whether to optimize focusing and drawing when displaying its NSViews. The optimizations may prevent sibling subviews from being displayed in the correct order-which matters only if the subviews overlap. You should always set flag to YES if there are no overlapping subviews within the NSWindow. The default is NO.
validRequestorForSendType:
(NSString *)sendType returnType:
(NSString *)returnType
Searches for an object that responds to a Services request by providing input of sendType and accepting output of returnType. Returns that object, or nil
if none is found.
Messages to perform this method are initiated by the Services menu. It's part of the mechanism that passes validRequestorForSendType:returnType:
messages up the responder chain. See the Services documentation in Programming Topics for more information.
This method works by forwarding the message to the receiver's delegate if it responds (and provided it isn't an NSResponder with its own next responder). If the delegate doesn't respond to the message or returns nil
when sent it, this method forwards the message to the NSApplication object. If the NSApplication object returns nil
, this method also returns nil
. Otherwise this method returns the object returned by the delegate or the NSApplication object.
See also:
- validRequestorForSendType:returnType:
(NSResponder and NSApplication)
viewsNeedDisplay
Returns YES if any of the receiver's NSView's need to be displayed, NO otherwise.
See also:
- setViewsNeedDisplay:
windowHandle
Returns a Microsoft Windows HWND handle as a pointer to void
. This value can be cast directly to HWND. This method exists only on Microsoft Windows; don't attempt to invoke it on Mach or Macintosh.
windowNumber
Returns the window number of the receiver's PostScript window device. Each window device in an application is given a unique window number-note that this isn't the same as the global window number assigned by the Window Server. This number can be used to identify the window device with the orderWindow:relativeTo:
method and in the Application Kit functions NSWindowList
and NSConvertWindowNumberToGlobal
.
If the receiver doesn't have a window device, the value returned will be equal to or less than 0.
See also:
- initWithContentRect:styleMask:backing:defer:
, - setOneShot:
worksWhenModal
Returns YES if the receiver is able to receive keyboard and mouse events even when some other window is being run modally, NO otherwise. NSWindow's implementation of this method returns NO. Only subclasses of NSPanel should override this default.
See also:
- setWorksWhenModal:
(NSPanel)
zoom:
(id)sender
Toggles the size and location of the window between its standard state (provided by the application as the "best" size to display the window's data) and its user state (a new size and location the user may have set by moving or resizing the window). For more information on the standard and user states, see windowWillUseStandardFrame:defaultFrame:
.
The zoom:
method is typically invoked after a user clicks the window's zoom box but may also be invoked programmatically from the performZoom:
method. It performs the following steps:
windowWillUseStandardFrame:defaultFrame:
method, if the delegate or the window class implements it, to obtain a "best fit" frame for the window. If neither the delegate nor the window class implements the method, uses a default frame that nearly fills the current screen, which is defined to be the screen containing the largest part of the window's current frame
windowShouldZoom:toFrame:
method, zoom:
invokes that method. If the delegate doesn't implement the method but the window does, zoom:
invokes the window's version. windowShouldZoom:toFrame:
returns NO if zooming is not currently allowed.
windowDidBecomeKey:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow has become key. aNotification is always NSWindowDidBecomeKeyNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowDidBecomeMain:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow has become main. aNotification is always NSWindowDidBecomeMainNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowDidChangeScreen:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow has changed screens. aNotification is always NSWindowDidChangeScreenNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowDidDeminiaturize:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow has been deminiaturized. aNotification is always NSWindowDidDeminiaturizeNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowDidExpose:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow has been exposed. aNotification is always NSWindowDidExposeNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowDidMiniaturize:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow has been miniaturized. aNotification is always NSWindowDidMiniaturizeNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowDidMove:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow has been moved. aNotification is always NSWindowDidMoveNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowDidResignKey:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow has resigned its status as key window. aNotification is always NSWindowDidResignKeyNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowDidResignMain:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow has resigned its status as main window. aNotification is always NSWindowDidResignMainNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowDidResize:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow has been resized. aNotification is always NSWindowDidResizeNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowDidUpdate:
(NSNotification *)aNotification
Sent by the default notification center immediately after an NSWindow receives an update
message. aNotification is always NSWindowDidUpdateNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowShouldClose:
(id)sender
Invoked when the user attempts to close the window or when the NSWindow receives a performClose:
message. The delegate can return NO to prevent sender from closing.
windowShouldZoom:
(NSWindow *)sender toFrame:
(NSRect)newFrame
Invoked just before sender is zoomed. Zooming will change the frame of sender to newFrame. The delegate can return NO to prevent sender from zooming.
See also:
- windowWillUseStandardFrame:defaultFrame:
windowWillClose:
(NSNotification *)aNotification
Sent by the default notification center immediately before an NSWindow closes. aNotification is always NSWindowWillCloseNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowWillMiniaturize:
(NSNotification *)aNotification
Sent by the default notification center immediately before an NSWindow is miniaturized. aNotification is always NSWindowWillMiniaturizeNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowWillMove:
(NSNotification *)aNotification
Sent by the default notification center immediately before an NSWindow is moved. aNotification is always NSWindowWillMoveNotification. You can retrieve the NSWindow object in question by sending object
to aNotification.
windowWillResize:
(NSWindow *)sender toSize:
(NSSize)proposedFrameSize
Invoked when sender is being resized (whether by the user or through one of the setFrame...
methods other than setFrame:display:
). proposedFrameSize contains the size (in screen coordinates) that the sender will be resized to. To resize to a different size, simply return the desired size from this method; to avoid resizing, return the current size. The NSWindow's minimum and maximum size constraints have already been applied when this method is invoked.
While the user is resizing an NSWindow, the delegate is sent a series of windowWillResize:toSize:
messages as the NSWindow's outline is dragged. The NSWindow's outline is displayed at the constrained size as set by this method.
windowWillReturnFieldEditor:
(NSWindow *)sender toObject:
(id)anObject
Invoked when the field editor of sender is requested by anObject. If the delegate's implementation of this method returns an object other than nil
, the NSWindow substitutes it for the field editor and returns it to anObject.
See also:
- fieldEditor:forObject:
windowWillUseStandardFrame:
(NSWindow *)sender
defaultFrame
(NSRect)defaultFrame
Invoked by the zoom:
method while determining a frame the window may be zoomed to. Returns the standard frame (described below) for window. The defaultFrame parameter passed in is the size of the current screen, which is the screen containing the largest part of the window's current frame, possibly reduced on the top, bottom, left, or right, depending on the current interface style. For the Macintosh style, for example, the frame is reduced on the top to leave room for the menu bar.
The standard frame for a window should supply the size and location that are "best" for the type of information shown in the window, taking into account the available display or displays. For example, the best width for a window that displays a word-processing document is the width of a page or the width of the display, whichever is smaller. The best height can be determined similarly. On return from this method, the zoom:
method modifies the returned standard frame, if necessary, to fit on the current screen.
To customize the standard state, you implement windowWillUseStandardFrame:defaultFrame:
in the class of the window's delegate or, if necessary, in a window subclass. Your version should return a suitable standard frame, based on the currently displayed data or other factors.
See also:
- windowShouldZoom:toFrame:
, - zoom:
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that has become key.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that has become main.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that has changed screens.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that has been deminiaturized.
This notification contains a notification object and a userInfo dictionary. The notification object is the NSWindow that has been exposed. The userInfo dictionary contains the key NSExposedRect and an associated value for the rectangle that has been exposed.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that has been miniaturized.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that has moved.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that has resigned its key window status.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that has resigned its main window status.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow whose size has changed.
update
message.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that received the update
message.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that is about to close.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that is about to be miniaturized.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSWindow that is about to move.