Next Page > Hide TOC

NSView Class Reference

Class at a Glance

NSView is a class that defines the basic drawing, event-handling, and printing architecture of an application. You typically don’t interact with the NSView API directly; rather, your custom view classes inherit from NSView and override many of its methods, which are invoked automatically by the Application Kit. If you’re not creating a custom view class, there are few methods you need to use.

Principal Attributes

• Event handling

• Integrated display to screen and printer

• Flexible coordinate systems

• Icon dragging

Commonly Used Methods

frame

Returns the location and size of the NSView object.

bounds

Returns the internal origin and size of the NSView object.

setNeedsDisplay:

Marks the NSView object as needing to be redrawn

window

Returns the NSWindow object that contains the NSView object.

drawRect:

Draws the NSView object. (All subclasses must implement this method, but it’s rarely invoked explicitly.)

Overview

The NSView class that provides a structure for drawing, printing, and handling events.

NSView objects (also know, simply, as view objects or views) are arranged within an NSWindow object, in a nested hierarchy of subviews. A view object claims a rectangular region of its enclosing superview, is responsible for all drawing within that region, and is eligible to receive mouse events occurring in it as well. In addition to these major responsibilities, NSView handles dragging of icons and works with the NSScrollView class to support efficient scrolling.

Most of the functionality of NSView either is automatically invoked by the Application Kit, or is available in Interface Builder. Unless you’re implementing a concrete subclass of NSView or working intimately with the content of the view hierarchy at runtime, you don’t need to know much about this class’s interface. See “Commonly Used Methods” for methods you might use regardless.

For more information on how NSView instances handle event and action messages, see Handling Events in Views, Handling Mouse Events in Views, and Handling Tracking-Rectangle and Cursor-Update Events in Views. For more information on displaying tooltips and contextual menus, see How Contextual Menus Work and Tooltips.

Subclassing Notes

NSView is perhaps the most important class in the Application Kit when it comes to subclassing and inheritance. Most user-interface objects you see in a Cocoa application are objects that inherit from NSView. If you want to create an object that draws itself in a special way, or that responds to mouse clicks in a special way, you would create a custom subclass of NSView (or of a class that inherits from NSView). Subclassing NSView is such a common and important procedure that several technical documents describe how to both draw in custom subclasses and respond to events in custom subclasses. See Cocoa Drawing Guide and Cocoa Event-Handling Guide (especially "Handling Events in Views" and "Handling Mouse Events in Views").

Tasks

Creating Instances

• – initWithFrame:

Managing the View Hierarchy

• – superview
• – setSubviews:
• – subviews
• – window
• – addSubview:
• – addSubview:positioned:relativeTo:
• – didAddSubview:
• – removeFromSuperview
• – removeFromSuperviewWithoutNeedingDisplay
• – replaceSubview:with:
• – isDescendantOf:
• – opaqueAncestor
• – ancestorSharedWithView:
• – sortSubviewsUsingFunction:context:
• – viewDidMoveToSuperview
• – viewDidMoveToWindow
• – viewWillMoveToSuperview:
• – viewWillMoveToWindow:
• – willRemoveSubview:
• – enclosingMenuItem

Searching by Tag

• – viewWithTag:
• – tag

Modifying the Frame Rectangle

• – setFrame:
• – frame
• – setFrameOrigin:
• – setFrameSize:
• – setFrameRotation:
• – frameRotation

Modifying the Bounds Rectangle

• – setBounds:
• – bounds
• – setBoundsOrigin:
• – setBoundsSize:
• – setBoundsRotation:
• – boundsRotation

Modifying the Coordinate System

• – translateOriginToPoint:
• – scaleUnitSquareToSize:
• – rotateByAngle:

Examining Coordinate System Modifications

• – isFlipped
• – isRotatedFromBase
• – isRotatedOrScaledFromBase

Base Coordinate Conversion

• – convertPointToBase:
• – convertPointFromBase:
• – convertSizeToBase:
• – convertSizeFromBase:
• – convertRectToBase:
• – convertRectFromBase:

Converting Coordinates

• – convertPoint:fromView:
• – convertPoint:toView:
• – convertSize:fromView:
• – convertSize:toView:
• – convertRect:fromView:
• – convertRect:toView:
• – centerScanRect:

Controlling Notifications

• – setPostsFrameChangedNotifications:
• – postsFrameChangedNotifications
• – setPostsBoundsChangedNotifications:
• – postsBoundsChangedNotifications

Resizing Subviews

• – resizeSubviewsWithOldSize:
• – resizeWithOldSuperviewSize:
• – setAutoresizesSubviews:
• – autoresizesSubviews
• – setAutoresizingMask:
• – autoresizingMask

Focusing

• – lockFocus
• – lockFocusIfCanDraw
• – lockFocusIfCanDrawInContext:
• – unlockFocus
• + focusView

Displaying

• – setNeedsDisplay:
• – setNeedsDisplayInRect:
• – needsDisplay
• – display
• – displayRect:
• – displayRectIgnoringOpacity:
• – displayRectIgnoringOpacity:inContext:
• – displayIfNeeded
• – displayIfNeededInRect:
• – displayIfNeededIgnoringOpacity
• – displayIfNeededInRectIgnoringOpacity:
• – translateRectsNeedingDisplayInRect:by:
• – isOpaque
• – viewWillDraw

Focus Ring Drawing

• – setKeyboardFocusRingNeedsDisplayInRect:
• + defaultFocusRingType
• – setFocusRingType:
• – focusRingType

Fullscreen Mode

• – enterFullScreenMode:withOptions:
• – exitFullScreenModeWithOptions:
• – isInFullScreenMode

Hiding Views

• – setHidden:
• – isHidden
• – isHiddenOrHasHiddenAncestor
• – viewDidHide
• – viewDidUnhide

Drawing

• – drawRect:
• – visibleRect
• – canDraw
• – shouldDrawColor
• – getRectsBeingDrawn:count:
• – needsToDrawRect:
• – wantsDefaultClipping
• – bitmapImageRepForCachingDisplayInRect:
• – cacheDisplayInRect:toBitmapImageRep:

Managing Live Resize

• – inLiveResize
• – preservesContentDuringLiveResize
• – getRectsExposedDuringLiveResize:count:
• – rectPreservedDuringLiveResize
• – viewWillStartLiveResize
• – viewDidEndLiveResize

Managing the Graphics State

• – allocateGState
• – gState
• – setUpGState
• – renewGState
• – releaseGState

Event Handling

• – acceptsFirstMouse:
• – hitTest:
• – mouse:inRect:
• – performKeyEquivalent:
• – performMnemonic:
• – mouseDownCanMoveWindow

Dragging Operations

• – dragImage:at:offset:event:pasteboard:source:slideBack:
• – dragFile:fromRect:slideBack:event:
• – registerForDraggedTypes:
• – registeredDraggedTypes
• – unregisterDraggedTypes
• – shouldDelayWindowOrderingForEvent:
• – dragPromisedFilesOfTypes:fromRect:source:slideBack:event:

Tool Tips

• – addToolTipRect:owner:userData:
• – removeAllToolTips
• – removeToolTip:
• – setToolTip:
• – toolTip

Managing Tracking Rectangles

• – addTrackingRect:owner:userData:assumeInside:
• – removeTrackingRect:

Managing Tracking Areas

• – addTrackingArea:
• – removeTrackingArea:
• – trackingAreas
• – updateTrackingAreas

Managing Cursor Tracking

• – addCursorRect:cursor:
• – removeCursorRect:cursor:
• – discardCursorRects
• – resetCursorRects

Scrolling

• – scrollPoint:
• – scrollRectToVisible:
• – autoscroll:
• – adjustScroll:
• – scrollRect:by:
• – enclosingScrollView
• – scrollClipView:toPoint:
• – reflectScrolledClipView:

Contextual Menus

• – menuForEvent:
• + defaultMenu

Key-view Loop Management

• – canBecomeKeyView
• – needsPanelToBecomeKey
• – setNextKeyView:
• – nextKeyView
• – nextValidKeyView
• – previousKeyView
• – previousValidKeyView

Printing

• – print:
• – beginPageInRect:atPlacement:
• – dataWithEPSInsideRect:
• – dataWithPDFInsideRect:
• – printJobTitle
• – pageFooter
• – pageHeader
• – writeEPSInsideRect:toPasteboard:
• – writePDFInsideRect:toPasteboard:
• – drawPageBorderWithSize:
• – drawSheetBorderWithSize:

Pagination

• – heightAdjustLimit
• – widthAdjustLimit
• – adjustPageWidthNew:left:right:limit:
• – adjustPageHeightNew:top:bottom:limit:
• – knowsPageRange:
• – rectForPage:
• – locationOfPrintRect:

Writing Conforming Rendering Instructions

• – beginDocument
• – endDocument
• – endPage

Core Animation Layer-Backing

• – setLayer:
• – layer
• – setWantsLayer:
• – wantsLayer

Core Animation Layer Properties

• – setFrameCenterRotation:
• – frameCenterRotation
• – setAlphaValue:
• – alphaValue
• – setBackgroundFilters:
• – backgroundFilters
• – setCompositingFilter:
• – compositingFilter
• – setContentFilters:
• – contentFilters
• – setShadow:
• – shadow

Class Methods

defaultFocusRingType

Returns the default focus ring type.

+ (NSFocusRingType)defaultFocusRingType

Return Value

The default type of focus ring for objects of the receiver’s class. Possible return values are listed in NSFocusRingType.

Discussion

If NSFocusRingTypeDefault is returned from the instance method focusRingType, the receiver can invoke this class method to find out what type of focus ring is the default. The receiver is free to ignore the default setting.

Availability

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

Declared In

defaultMenu

Overridden by subclasses to return the default pop-up menu for instances of the receiving class.

+ (NSMenu *)defaultMenu

Discussion

The default implementation returns nil.

Availability

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

See Also

• – menuForEvent:
• – menu (NSResponder)

Declared In

focusView

Returns the currently focused NSView object, or nil if there is none.

+ (NSView *)focusView

Availability

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

See Also

• – lockFocus
• – unlockFocus

Declared In

Instance Methods

acceptsFirstMouse:

Overridden by subclasses to return YES if the receiver should be sent a mouseDown: message for an initial mouse-down event, NO if not.

- (BOOL)acceptsFirstMouse:(NSEvent *)theEvent

Parameters

theEvent

The initial mouse-down event, which must be over the receiver in its window.

Discussion

The receiver can either return a value unconditionally or use the location of theEvent to determine whether or not it wants the event. The default implementation ignores theEvent and returns NO.

Override this method in a subclass to allow instances to respond to click-through. This allows the user to click on a view in an inactive window, activating the view with one click, instead of clicking first to make the window active and then clicking the view. Most view objects refuse a click-through attempt, so the event simply activates the window. Many control objects, however, such as instances of NSButton and NSSlider, do accept them, so the user can immediately manipulate the control without having to release the mouse button.

Availability

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

See Also

• – hitTest:

Declared In

addCursorRect:cursor:

Establishes the cursor to be used when the mouse pointer lies within a specified region.

- (void)addCursorRect:(NSRect)aRect cursor:(NSCursor *)aCursor

Parameters

aRect

A rectangle defining a region of the receiver.

aCursor

An object representing a cursor.

Discussion

Cursor rectangles aren’t subject to clipping by superviews, nor are they intended for use with rotated views. You should explicitly confine a cursor rectangle to the view's visible rectangle to prevent improper behavior.

This method is intended to be invoked only by the resetCursorRects method. If invoked in any other way, the resulting cursor rectangle will be discarded the next time the view's cursor rectangles are rebuilt.

Availability

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

See Also

• – removeCursorRect:cursor:
• – discardCursorRects
• – resetCursorRects
• – visibleRect

Declared In

addSubview:

Adds a view to the receiver’s subviews so it’s displayed above its siblings.

- (void)addSubview:(NSView *)aView

Parameters

aView

The view to add to the receiver as a subview.

Discussion

This method also sets the receiver as the next responder of aView.

The receiver retains aView. If you use removeFromSuperview to remove aView from the view hierarchy, aView is released. If you want to keep using aView after removing it from the view hierarchy (if, for example, you are swapping through a number of views), you must retain it before invoking removeFromSuperview.

Availability

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

See Also

• – addSubview:positioned:relativeTo:
• – subviews
• – removeFromSuperview
• – setNextResponder: (NSResponder)
• – viewWillMoveToSuperview:
• – viewWillMoveToWindow:

Related Sample Code

• iSpend
• Quartz Composer WWDC 2005 TextEdit
• Sketch-112
• TextEditPlus
• WhackedTV

Declared In

addSubview:positioned:relativeTo:

Inserts a view among the receiver’s subviews so it’s displayed immediately above or below another view.

- (void)addSubview:(NSView *)aView positioned:(NSWindowOrderingMode)place relativeTo:(NSView *)otherView

Parameters

aView

The view object to add to the receiver as a subview.

place

An enum constant specifying the position of the aView relative to otherView. Valid values are NSWindowAbove or NSWindowBelow.

otherView

The other view aView is to be positioned relative to. If otherView is nil (or isn’t a subview of the receiver), aView is added above or below all of its new siblings.

Discussion

This method also sets the receiver as the next responder of aView.

The receiver retains aView. If you use removeFromSuperview to remove aView from the view hierarchy, aView is released. If you want to keep using aView after removing it from the view hierarchy (if, for example, you are swapping through a number of views), you must retain it before invoking removeFromSuperview.

Availability

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

See Also

• – addSubview:
• – subviews
• – removeFromSuperview
• – setNextResponder: (NSResponder)

Declared In

addToolTipRect:owner:userData:

Creates a tool tip for a defined area the receiver and returns a tag that identifies the tool tip rectangle.

- (NSToolTipTag)addToolTipRect:(NSRect)aRect owner:(id)anObject userData:(void *)userData

Parameters

aRect

A rectangle defining the region of the receiver to associate the tool tip with.

anObject

An object from which to obtain the tool tip string. The object should either implement view:stringForToolTip:point:userData:, or return a suitable string from its description method. (It can therefore simply be an NSString object.)

Important: The receiver maintains a weak reference to anObject. You are responsible for ensuring that anObject remains valid for as long as it may be needed.

userData

Any additional information you want to pass to view:stringForToolTip:point:userData:; it is not used if anObject does not implement this method.

Return Value

An integer tag identifying the tool tip; you can use this tag to remove the tool tip.

Discussion

The tool tip string is obtained dynamically from anObject by invoking either the NSToolTipOwner informal protocol method view:stringForToolTip:point:userData:, if implemented, or the NSObject protocol method description.

Availability

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

See Also

• – removeToolTip:
• – removeAllToolTips

Declared In

addTrackingArea:

Adds a given tracking area to the receiver.

- (void)addTrackingArea:(NSTrackingArea *)trackingArea

Parameters

trackingArea

The tracking area to add to the receiver.

Availability

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

Related Sample Code

• BasicCocoaAnimations

Declared In

addTrackingRect:owner:userData:assumeInside:

Establishes an area for tracking mouse-entered and mouse-exited events within the receiver and returns a tag that identifies the tracking rectangle.

- (NSTrackingRectTag)addTrackingRect:(NSRect)aRect owner:(id)userObject userData:(void *)userData assumeInside:(BOOL)flag

Parameters

aRect

A rectangle that defines a region of the receiver for tracking mouse-entered and mouse-exited events.

userObject

The object that gets sent the event messages. It can be the receiver itself or some other object (such as an NSCursor or a custom drawing tool object), as long as it responds to both mouseEntered: and mouseExited:.

userData

Data stored in the NSEvent object for each tracking event.

flag

If YES, the first event will be generated when the cursor leaves aRect, regardless if the cursor is inside aRect when the tracking rectangle is added. If NO the first event will be generated when the cursor leaves aRect if the cursor is initially inside aRect, or when the cursor enters aRect if the cursor is initially outside aRect. You usually want to set this flag to NO.

Return Value

A tag that identifies the tracking rectangle. It is stored in the associated NSEvent objects and can be used to remove the tracking rectangle.

Discussion

Tracking rectangles provide a general mechanism that can be used to trigger actions based on the cursor location (for example, a status bar or hint field that provides information on the item the cursor lies over). To simply change the cursor over a particular area, use addCursorRect:cursor:. If you must use tracking rectangles to change the cursor, the NSCursor class specification describes the additional methods that must be invoked to change cursors by using tracking rectangles.

On Mac OS X v10.5 and later, tracking areas provide a greater range of functionality (see addTrackingArea:).

Availability

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

See Also

• – removeTrackingRect:
• – addTrackingArea:
• – userData (NSEvent)

Related Sample Code

• FunkyOverlayWindow

Declared In

adjustPageHeightNew:top:bottom:limit:

Overridden by subclasses to adjust page height during automatic pagination.

- (void)adjustPageHeightNew:(CGFloat *)newBottom top:(CGFloat)top bottom:(CGFloat)proposedBottom limit:(CGFloat)bottomLimit

Parameters

newBottom

Returns by indirection a new float value for the bottom edge of the pending page rectangle in the receiver's coordinate system.

top

A float value that sets the top edge of the pending page rectangle in the receiver’s coordinate system.

proposedBottom

A float value that sets the bottom edge of the pending page rectangle in the receiver’s coordinate system.

bottomLimit

The topmost float value newBottom can be set to, as calculated using the return value of heightAdjustLimit.

Discussion

This method is invoked by print:. The receiver can raise the bottom edge and return the new value in newBottom, allowing it to prevent items such as lines of text from being divided across pages. If bottomLimit is exceeded, the pagination mechanism simply uses bottomLimit for the bottom edge.

The default implementation of this method propagates the message to its subviews, allowing nested views to adjust page height for their drawing as well. An NSButton object or other small view, for example, will nudge the bottom edge up if necessary to prevent itself from being cut in two (thereby pushing it onto an adjacent page). Subclasses should invoke super’s implementation, if desired, after first making their own adjustments.

Availability

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

See Also

• – adjustPageWidthNew:left:right:limit:

Declared In

adjustPageWidthNew:left:right:limit:

Overridden by subclasses to adjust page width during automatic pagination.

- (void)adjustPageWidthNew:(CGFloat *)newRight left:(CGFloat)left right:(CGFloat)proposedRight limit:(CGFloat)rightLimit

Parameters

newRight

Returns by indirection a new float value for the right edge of the pending page rectangle in the receiver's coordinate system.

left

A float value that sets the left edge of the pending page rectangle in the receiver’s coordinate system.

proposedRight

A float value that sets the right edge of the pending page rectangle in the receiver’s coordinate system.

rightLimit

The leftmost float value newRight can be set to, as calculated using the return value of widthAdjustLimit.

Discussion

This method is invoked by print:. The receiver can pull in the right edge and return the new value in newRight, allowing it to prevent items such as small images or text columns from being divided across pages. If rightLimit is exceeded, the pagination mechanism simply uses rightLimit for the right edge.

The default implementation of this method propagates the message to its subviews, allowing nested views to adjust page width for their drawing as well. An NSButton object or other small view, for example, will nudge the right edge out if necessary to prevent itself from being cut in two (thereby pushing it onto an adjacent page). Subclasses should invoke super’s implementation, if desired, after first making their own adjustments.

Availability

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

See Also

• – adjustPageHeightNew:top:bottom:limit:

Declared In

adjustScroll:

Overridden by subclasses to modify a given rectangle, returning the altered rectangle.

- (NSRect)adjustScroll:(NSRect)proposedVisibleRect

Parameters

proposedVisibleRect

A rectangle defining a region of the receiver.

Discussion

NSClipView invokes this method to allow its document view to adjust its position during scrolling. For example, a custom view object that displays a table of data can adjust the origin of proposedVisibleRect so rows or columns aren’t cut off by the edge of the enclosing NSClipView. NSView’s implementation simply returns proposedVisibleRect.

NSClipView only invokes this method during automatic or user controlled scrolling. Its scrollToPoint: method doesn’t invoke this method, so you can still force a scroll to an arbitrary point.

Availability

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

Declared In

allocateGState

Causes the receiver to maintain a private graphics state object, which encapsulates all parameters of the graphics environment.

- (void)allocateGState

Discussion

If you do not invoke allocateGState, a graphics state object is constructed from scratch each time the NSView is focused.

The receiver builds the graphics state parameters using setUpGState, then automatically establishes this graphics state each time the focus is locked on it. A graphics state may improve performance for view objects that are focused often and need to set many parameters, but use of standard rendering operators is normally efficient enough.

Because graphics states occupy a fair amount of memory, they can actually degrade performance. Be sure to test application performance with and without the private graphics state before committing to its use.

Availability

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

See Also

• – setUpGState
• – gState
• – renewGState
• – releaseGState
• – lockFocus

Declared In

alphaValue

Returns the opacity of the receiver

- (CGFloat)alphaValue

Return Value

The current opacity of the receiver

Discussion

This method returns the value of the opacity property of the receiver’s layer. Possible values are between 0.0 (transparent) and 1.0 (opaque). The default is 1.0.

Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Related Sample Code

• RoundTransparentWindow

Declared In

ancestorSharedWithView:

Returns the closest ancestor shared by the receiver and a given view.

- (NSView *)ancestorSharedWithView:(NSView *)aView

Parameters

aView

The view to test (along with the receiver) for closest shared ancestor.

Return Value

The closest ancestor or nil if there’s no such object. Returns self if aView is identical to the receiver.

Availability

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

See Also

• – isDescendantOf:

Declared In

autoresizesSubviews

Returns YES if the receiver automatically resizes its subviews using resizeSubviewsWithOldSize: whenever its frame size changes, NO otherwise.

- (BOOL)autoresizesSubviews

Availability

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

See Also

• – setAutoresizesSubviews:

Declared In

autoresizingMask

Returns the receiver’s autoresizing mask, which determines how it’s resized by the resizeWithOldSuperviewSize: method.

- (NSUInteger)autoresizingMask

Return Value

An integer bit mask specified by combining using the C bitwise OR operator any of the options described in “Resizing masks”.

Discussion

If the autoresizing mask is equal to NSViewNotSizable (that is, if none of the options are set), then the receiver doesn’t resize at all in resizeWithOldSuperviewSize:.

Availability

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

Related Sample Code

• PredicateEditorSample

Declared In

autoscroll:

Scrolls the receiver’s closest ancestor NSClipView object proportionally to the distance of an event that occurs outside of it.

- (BOOL)autoscroll:(NSEvent *)theEvent

Parameters

theEvent

An event object whose location should be expressed in the window’s base coordinate system (which it normally is), not the receiving view's.

Return Value

Returns YES if any scrolling is performed; otherwise returns NO.

Discussion

View objects that track mouse-dragged events can use this method to scroll automatically when the cursor is dragged outside of the NSClipView object. Repeated invocations of this method (with an appropriate delay) result in continual scrolling, even when the mouse doesn’t move.

Availability

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

See Also

• – autoscroll: (NSClipView)
• – scrollPoint:
• – isDescendantOf:

Declared In

backgroundFilters

Returns the array of CoreImage filters that are applied to the receiver’s background

- (NSArray *)backgroundFilters

Return Value

An array of CoreImage filters.

Discussion

This method returns the value of the backgroundFilters property of the receiver’s layer.

Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

beginDocument

Invoked at the beginning of the printing session, this method sets up the current graphics context.

- (void)beginDocument

Discussion

Note that this method may be invoked in a subthread.

Override it to configure printing related settings. You should store your settings in the object returned by NSPrintInfo‘s sharedPrintInfo class method, which is guaranteed to return an instance specific to the thread in which you invoke this method. If you override this method, call the superclass implementation.

Availability

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

Declared In

beginPageInRect:atPlacement:

Called at the beginning of each page, this method sets up the coordinate system so that a region inside the receiver’s bounds is translated to a specified location..

- (void)beginPageInRect:(NSRect)aRect atPlacement:(NSPoint)location

Parameters

aRect

A rectangle defining the region to be translated.

location

A point that is the end-point of translation.

Discussion

If you override this method, be sure to call the superclass implementation.

Availability

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

Declared In

bitmapImageRepForCachingDisplayInRect:

Returns a bitmap-representation object suitable for caching the specified portion of the receiver.

- (NSBitmapImageRep *)bitmapImageRepForCachingDisplayInRect:(NSRect)aRect

Parameters

aRect

A rectangle defining the area of the receiver to be cached.

Return Value

An autoreleased NSBitmapImageRep object or nil if the object could not be created.

Discussion

Passing the visible rectangle of the receiver ([self visibleRect]) returns a bitmap suitable for caching the current contents of the view, including all of its descendants.

Availability

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

See Also

• – cacheDisplayInRect:toBitmapImageRep:

Related Sample Code

• CarbonCocoaCoreImageTab
• Reducer

Declared In

bounds

Returns the receiver’s bounds rectangle, which expresses its location and size in its own coordinate system.

- (NSRect)bounds

Discussion

By default, the origin of the returned rectangle is (0, 0) and its size matches the size of the receiver’s frame rectangle (measured in points). In Mac OS X v10.5 and later, if the receiver is being rendered into an OpenGL graphics context (using an NSOpenGLContext object), the default bounds origin is still (0, 0) but the default bounds size is measured in pixels instead of points. Thus, for user space scale factors other than 1.0, the default size of the bounds rectangle may be bigger or smaller than the default size of the frame rectangle when drawing with OpenGL.

If you explicitly change the origin or size of the bounds rectangle, this method does not return the default rectangle and instead returns the rectangle you set. If you add a rotation factor to the view, however, that factor is also reflected in the returned bounds rectangle. You can determine if a rotation factor is in effect by calling the boundsRotation method.

Availability

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

See Also

• – frame
• – setBounds:

Related Sample Code

• Cocoa - SGDataProc
• GLChildWindowDemo
• LiveVideoMixer2
• Sketch-112
• WhackedTV

Declared In

boundsRotation

Returns the angle, in degrees, of the receiver’s bounds rectangle relative to its frame rectangle.

- (CGFloat)boundsRotation

Discussion

See the setBoundsRotation: method description for more information on bounds rotation.

Availability

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

See Also

• – rotateByAngle:
• – setBoundsRotation:

Declared In

cacheDisplayInRect:toBitmapImageRep:

Draws the specified area of the receiver, and its descendants, into a provided bitmap-representation object.

- (void)cacheDisplayInRect:(NSRect)rect toBitmapImageRep:(NSBitmapImageRep *)bitmapImageRep

Parameters

rect

A rectangle defining the region to be drawn into bimapImageRep.

bitmapImageRep

An NSBitmapImageRep object. For pixel-format compatibility, bitmapImageRep should have been obtained from bitmapImageRepForCachingDisplayInRect:.

Discussion

You are responsible for initializing the bitmap to the desired configuration before calling this method. However, once initialized, you can reuse the same bitmap multiple times to refresh the cached copy of your view’s contents.

The bitmap produced by this method is transparent (that is, has an alpha value of 0) wherever the receiver and its descendants do not draw any content.

Availability

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

See Also

• – bitmapImageRepForCachingDisplayInRect:

Related Sample Code

• CarbonCocoaCoreImageTab
• Reducer

Declared In

canBecomeKeyView

Returns YES if the receiver can become key view, NO otherwise.

- (BOOL)canBecomeKeyView

Availability

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

Declared In

canDraw

Returns YES if drawing commands will produce any result, NO otherwise.

- (BOOL)canDraw

Discussion

Use this method when invoking a draw method directly along with lockFocus and unlockFocus, bypassing the display... methods (which test drawing ability and perform locking for you). If this method returns NO, you shouldn’t invoke lockFocus or perform any drawing.

A view object can draw on-screen if it is not hidden, it is attached to a view hierarchy in a window (NSWindow), and the window has a corresponding window device. A view object can draw during printing if it is a descendant of the view being printed.

Availability

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

See Also

• – setHidden:

Declared In

centerScanRect:

Converts the corners of a specified rectangle to lie on the center of device pixels, which is useful in compensating for rendering overscanning when the coordinate system has been scaled.

- (NSRect)centerScanRect:(NSRect)aRect

Parameters

aRect

The rectangle whose corners are to be converted.

Return Value

The adjusted rectangle.

Discussion

This method converts the given rectangle to device coordinates, adjusts the rectangle to lie in the center of the pixels, and converts the resulting rectangle back to the receiver’s coordinate system. Note that this method does not take into account any transformations performed using the NSAffineTransform class or Quartz 2D routines.

Availability

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

See Also

• – isRotatedOrScaledFromBase

Related Sample Code

• Sketch-112

Declared In

compositingFilter

Returns the CoreImage filter that is used to composite the receiver’s contents with the background

- (CIFilter *)compositingFilter

Return Value

The CoreImage filter.

Discussion

This method returns the value of the filters property of the receiver’s layer.

Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

contentFilters

Returns the array of CoreImage filters that are applied to the contents of the receiver and its sublayers.

- (NSArray *)contentFilters

Return Value

An array of CoreImage filters

Discussion

This method returns the value of the filters property of the receiver’s layer.

Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

convertPoint:fromView:

Converts a point from the coordinate system of a given view to that of the receiver.

- (NSPoint)convertPoint:(NSPoint)aPoint fromView:(NSView *)aView

Parameters

aPoint

A point specifying a location in the coordinate system of aView.

aView

The view with aPoint in its coordinate system. If aView is nil, this method instead converts from window base coordinates. Otherwise, both aView and the receiver must belong to the same NSWindow object.

Return Value

The point converted to the coordinate system of the receiver.

Availability

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

See Also

• – convertRect:fromView:
• – convertSize:fromView:
• – ancestorSharedWithView:
• – contentView (NSWindow)

Related Sample Code

• CIAnnotation
• Clock Control
• LiveVideoMixer2
• Sketch-112
• TextLinks

Declared In

convertPoint:toView:

Converts a point from the receiver’s coordinate system to that of a given view.

- (NSPoint)convertPoint:(NSPoint)aPoint toView:(NSView *)aView

Parameters

aPoint

A point specifying a location in the coordinate system of the receiver.

aView

The view into whose coordinate system aPoint is to be converted. If aView is nil, this method instead converts to window base coordinates. Otherwise, both aView and the receiver must belong to the same NSWindow object.

Return Value

The point converted to the coordinate system of aView.

Availability

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

See Also

• – convertRect:toView:
• – convertSize:toView:
• – ancestorSharedWithView:
• – contentView (NSWindow)

Declared In

convertPointFromBase:

Converts the point from the base coordinate system to the receiver’s coordinate system.

- (NSPoint)convertPointFromBase:(NSPoint)aPoint

Parameters

aPoint

A point specifying a location in the base coordinate system.

Return Value

The point converted to the receiver’s base coordinate system.

Discussion

See View Coordinate Conversion in View Programming Guide for Cocoa for a description of view coordinate to base coordinate conversion.

Availability

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

Declared In

convertPointToBase:

Converts the point from the receiver’s coordinate system to the base coordinate system.

- (NSPoint)convertPointToBase:(NSPoint)aPoint

Parameters

aPoint

A point specifying a location in the coordinate system of the receiver.

Return Value

The point converted to the base coordinate system.

Discussion

See View Coordinate Conversion in View Programming Guide for Cocoa for a description of view coordinate to base coordinate conversion.

Availability

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

Declared In

convertRect:fromView:

Converts a rectangle from the coordinate system of another view to that of the receiver.

- (NSRect)convertRect:(NSRect)aRect fromView:(NSView *)aView

Parameters

aRect

The rectangle in aView's coordinate system.

aView

The view with aRect in its coordinate system. If aView is nil, this method instead converts from window base coordinates. Otherwise, both aView and the receiver must belong to the same NSWindow object.

Return Value

The converted rectangle.

Availability

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

See Also

• – convertPoint:fromView:
• – convertSize:fromView:
• – ancestorSharedWithView:
• – contentView (NSWindow)

Declared In

convertRect:toView:

Converts a rectangle from the receiver’s coordinate system to that of another view.

- (NSRect)convertRect:(NSRect)aRect toView:(NSView *)aView

Parameters

aRect

A rectangle in the receiver's coordinate system.

aView

The view that is the target of the conversion operation. If aView is nil, this method instead converts from window base coordinates. Otherwise, both aView and the receiver must belong to the same NSWindow object.

Return Value

The converted rectangle.

Availability

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

See Also

• – convertPoint:toView:
• – convertSize:toView:
• – ancestorSharedWithView:
• – contentView (NSWindow)

Declared In

convertRectFromBase:

Converts the rectangle from the base coordinate system to the receiver’s coordinate system.

- (NSRect)convertRectFromBase:(NSRect)aRect

Parameters

aRect

A rectangle in the base coordinate system

Return Value

A rectangle in the receiver’s coordinate system

Discussion

See View Coordinate Conversion in View Programming Guide for Cocoa for a description of view coordinate to base coordinate conversion.

Availability

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

Declared In

convertRectToBase:

Converts the rectangle from the receiver’s coordinate system to the base coordinate system.

- (NSRect)convertRectToBase:(NSRect)aRect

Parameters

aRect

A rectangle in the receiver’s coordinate system

Return Value

A rectangle in the base coordinate system

Discussion

See View Coordinate Conversion in View Programming Guide for Cocoa for a description of view coordinate to base coordinate conversion.

Availability

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

Declared In

convertSize:fromView:

Converts a size from another view’s coordinate system to that of the receiver.

- (NSSize)convertSize:(NSSize)aSize fromView:(NSView *)aView

Parameters

aSize

The size (width and height) in aView's coordinate system.

aView

The view with aSize in its coordinate system. If aView is nil, this method instead converts from window base coordinates. Otherwise, both aView and the receiver must belong to the same NSWindow object.

Return Value

The converted size, as an NSSize structure.

Availability

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

See Also

• – convertPoint:fromView:
• – convertRect:fromView:
• – ancestorSharedWithView:
• – contentView (NSWindow)

Declared In

convertSize:toView:

Converts a size from the receiver’s coordinate system to that of another view.

- (NSSize)convertSize:(NSSize)aSize toView:(NSView *)aView

Parameters

aSize

The size (width and height) in the receiver's coordinate system.

aView

The view that is the target of the conversion operation. If aView is nil, this method instead converts from window base coordinates. Otherwise, both aView and the receiver must belong to the same NSWindow object.

Return Value

The converted size, as an NSSize structure.

Availability

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

See Also

• – convertPoint:toView:
• – convertRect:toView:
• – ancestorSharedWithView:
• – contentView (NSWindow)

Declared In

convertSizeFromBase:

Converts the size from the base coordinate system to the receiver’s coordinate system.

- (NSSize)convertSizeFromBase:(NSSize)aSize

Parameters

aSize

A size in the base coordinate system

Return Value

The size converted to the receiver’s coordinate system.

Discussion

See View Coordinate Conversion in View Programming Guide for Cocoa for a description of view coordinate to base coordinate conversion.

Availability

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

Declared In

convertSizeToBase:

Converts the size from the receiver’s coordinate system to the base coordinate system.

- (NSSize)convertSizeToBase:(NSSize)aSize

Parameters

aSize

A size in the receiver’s coordinate system

Return Value

The size converted to the base coordinate system.

Discussion

See View Coordinate Conversion in View Programming Guide for Cocoa for a description of view coordinate to base coordinate conversion.

Availability

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

Declared In

dataWithEPSInsideRect:

Returns EPS data that draws the region of the receiver within a specified rectangle.

- (NSData *)dataWithEPSInsideRect:(NSRect)aRect

Parameters

aRect

A rectangle defining the region.

Discussion

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

Availability

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

See Also

• – writeEPSInsideRect:toPasteboard:

Declared In

dataWithPDFInsideRect:

Returns PDF data that draws the region of the receiver within a specified rectangle.

- (NSData *)dataWithPDFInsideRect:(NSRect)aRect

Parameters

aRect

A rectangle defining the region.

Discussion

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

Availability

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

See Also

• – writePDFInsideRect:toPasteboard:

Related Sample Code

• Sketch-112

Declared In

didAddSubview:

Overridden by subclasses to perform additional actions when subviews are added to the receiver.

- (void)didAddSubview:(NSView *)subview

Parameters

subview

The view that was added as a subview.

Discussion

This method is invoked by addSubview:.

Availability

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

Declared In

discardCursorRects

Invalidates all cursor rectangles set up using addCursorRect:cursor:.

- (void)discardCursorRects

Discussion

You need never invoke this method directly; neither is it typically invoked during the invalidation of cursor rectangles. NSWindow automatically invalidates cursor rectangles in response to invalidateCursorRectsForView: and before the receiver's cursor rectangles are reestablished using resetCursorRects. This method is invoked just before the receiver is removed from a window and when the receiver is deallocated.

Availability

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

See Also

• – discardCursorRects (NSWindow)

Declared In

display

Displays the receiver and all its subviews if possible, invoking each the NSView methods lockFocus, drawRect:, and unlockFocus as necessary.

- (void)display

Discussion

If the receiver isn’t opaque, this method backs up the view hierarchy to the first opaque ancestor, calculates the portion of the opaque ancestor covered by the receiver, and begins displaying from there.

Availability

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

See Also

• – canDraw
• – opaqueAncestor
• – visibleRect
• – displayIfNeededIgnoringOpacity

Related Sample Code

• CIVideoDemoGL
• Cocoa - SGDataProc
• LiveVideoMixer2
• StickiesExample

Declared In

displayIfNeeded

Displays the receiver and all its subviews if any part of the receiver has been marked as needing display with a setNeedsDisplay: or setNeedsDisplayInRect: message.

- (void)displayIfNeeded

Discussion

This method invokes the NSView methods lockFocus, drawRect:, and unlockFocus as necessary. If the receiver isn’t opaque, this method backs up the view hierarchy to the first opaque ancestor, calculates the portion of the opaque ancestor covered by the receiver, and begins displaying from there.

Availability

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

See Also

• – display
• – needsDisplay
• – displayIfNeededIgnoringOpacity

Declared In

displayIfNeededIgnoringOpacity

Acts as displayIfNeeded, except that this method doesn’t back up to the first opaque ancestor—it simply causes the receiver and its descendants to execute their drawing code.

- (void)displayIfNeededIgnoringOpacity

Availability

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

Declared In

displayIfNeededInRect:

Acts as displayIfNeeded, confining drawing to a specified region of the receiver..

- (void)displayIfNeededInRect:(NSRect)aRect

Parameters

aRect

A rectangle defining the region to be redrawn. It should be specified in the coordinate system of the receiver.

Availability

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

Declared In

displayIfNeededInRectIgnoringOpacity:

Acts as displayIfNeeded, but confining drawing to aRect and not backing up to the first opaque ancestor—it simply causes the receiver and its descendants to execute their drawing code.

- (void)displayIfNeededInRectIgnoringOpacity:(NSRect)aRect

Parameters

aRect

A rectangle defining the region to be redrawn. It should be specified in the coordinate system of the receiver.

Availability

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

Declared In

displayRect:

Acts as display, but confining drawing to a rectangular region of the receiver.

- (void)displayRect:(NSRect)aRect

Parameters

aRect

A rectangle defining the region of the receiver to be redrawn; should be specified in the coordinate system of the receiver.

Availability

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

Declared In

displayRectIgnoringOpacity:

Displays the receiver but confines drawing to a specified region and does not back up to the first opaque ancestor—it simply causes the receiver and its descendants to execute their drawing code.

- (void)displayRectIgnoringOpacity:(NSRect)aRect

Parameters

aRect

A rectangle defining the region of the receiver to be redrawn; should be specified in the coordinate system of the receiver.

Availability

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

Declared In

displayRectIgnoringOpacity:inContext:

Causes the receiver and its descendants to be redrawn to the specified graphics context.

- (void)displayRectIgnoringOpacity:(NSRect)aRect inContext:(NSGraphicsContext *)context

Parameters

aRect

A rectangle defining the region of the receiver to be redrawn. It should be specified in the coordinate system of the receiver.

context

The graphics context in which drawing will occur. See the discussion below for more about this parameter.

Discussion

Acts as display, but confines drawing to aRect. This method initiates drawing with the receiver, even if the receiver is not opaque. Appropriate scaling factors for the view are obtained from context.

If the context parameter represents the context for the window containing the view, then all of the necessary transformations are applied. This includes the application of the receiver’s bounds and frame transforms along with any transforms it inherited from its ancestors. In this situation, the view is also marked as no longer needing an update for the specified rectangle.

If context specifies any other graphics context, then only the receiver’s bounds transform is applied. This means that drawing is not constrained to the view’s visible rectangle. It also means that any dirty rectangles are not cleared, since they are not being redrawn to the window.

Availability

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

Declared In

dragFile:fromRect:slideBack:event:

Initiates a dragging operation from the receiver, allowing the user to drag a file icon to any application that has window or view objects that accept files.

- (BOOL)dragFile:(NSString *)fullPath fromRect:(NSRect)aRect slideBack:(BOOL)slideBack event:(NSEvent *)theEvent

Parameters

fullPath

A string that specifies the absolute path for the file that is dragged.

aRect

A rectangle that describes the position of the icon in the receiver’s coordinate system.

slideBack

A Boolean that indicates whether the icon being dragged should slide back to its position in the receiver if the file isn’t accepted. The icon slides back to aRect if slideBack is YES, the file is not accepted by the dragging destination, and the user has not disabled icon animation; otherwise it simply disappears.

theEvent

The mouse-down event object from which to initiate the drag operation. In particular, its mouse location is used for the offset of the icon being dragged.

Return Value

YES if the receiver successfully initiates the dragging operation (which doesn’t necessarily mean the dragging operation concluded successfully). Otherwise returns NO.

Discussion

This method must be invoked only within an implementation of the mouseDown: method.

See the NSDraggingSource, NSDraggingInfo, and NSDraggingDestination protocol specifications for more information on dragging operations.

Availability

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

See Also

• – dragImage:at:offset:event:pasteboard:source:slideBack:
• – shouldDelayWindowOrderingForEvent:

Declared In

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

Initiates a dragging operation from the receiver, allowing the user to drag arbitrary data with a specified icon into any application that has window or view objects that accept dragged data.

- (void)dragImage:(NSImage *)anImage at:(NSPoint)imageLoc offset:(NSSize)mouseOffset event:(NSEvent *)theEvent pasteboard:(NSPasteboard *)pboard source:(id)sourceObject slideBack:(BOOL)slideBack

Parameters

anImage

The NSImage object to be dragged.

imageLoc

The location of the image’s lower-left corner, in the receiver’s coordinate system. It determines the placement of the dragged image under the cursor. When determining the image location you should use the mouse down coordinate, provided in theEvent, rather than the current mouse location.

mouseOffset

The mouse’s current location relative to the mouse-down location. In Mac OS X v10.4 and later, this parameter is ignored. In earlier versions of Mac OS X, this parameter is ignored when positioning the dragged image on screen but not ignored when passing the drag location to the source in draggedImage:endedAt:operation:.

Historically, this argument represented the difference between the mouse position when the drag operation commenced and the mouse position of the initial mouse down. If you initiated a dragging operation immediately on a mouse-down event, this offset was (0.0, 0.0). If you tested for a mouse-dragged event first, this offset was the difference between the mouse-dragged event’s location and that of the mouse-down event. Since the underlying drag machinery now takes the current mouse position into account when positioning the drag image, this argument is no longer necessary

theEvent

The left mouse-down event that triggered the dragging operation (see discussion below).

pboard

The pasteboard that holds the data to be transferred to the destination (see discussion below).

sourceObject

An object that serves as the controller of the dragging operation. It must conform to the NSDraggingSource informal protocol and is typically the receiver itself or its NSWindow object.

slideBack

A Boolean that determines whether the drag image should slide back if it’s rejected. The image slides back to imageLoc if slideBack is YES and the image isn’t accepted by the dragging destination. If NO the image doesn't slide back.

Discussion

This method must be invoked only within an implementation of the mouseDown: or mouseDragged: methods.

Before invoking this method, you must place the data to be transferred on pboard. To do this, get the drag pasteboard object (NSDragPboard), declare the types of the data, and then put the data on the pasteboard. This code fragment initiates a dragging operation on an image itself (that is, the image is the data to be transferred):

- (void)mouseDown:(NSEvent *)theEvent

{

    NSSize dragOffset = NSMakeSize(0.0, 0.0);

    NSPasteboard *pboard;

    pboard = [NSPasteboard pasteboardWithName:NSDragPboard];

    [pboard declareTypes:[NSArray arrayWithObject:NSTIFFPboardType]  owner:self];

    [pboard setData:[[self image] TIFFRepresentation] forType:NSTIFFPboardType];

    [self dragImage:[self image] at:[self imageLocation] offset:dragOffset

        event:theEvent pasteboard:pboard source:self slideBack:YES];

    return;

}

See the NSDraggingSource, NSDraggingInfo, and NSDraggingDestination protocol specifications for more information on dragging operations.

Availability

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

See Also

• – dragFile:fromRect:slideBack:event:
• – shouldDelayWindowOrderingForEvent:

Declared In

dragPromisedFilesOfTypes:fromRect:source:slideBack:event:

Initiates a dragging operation from the receiver, allowing the user to drag one or more promised files (or directories) into any application that has window or view objects that accept promised file data.

- (BOOL)dragPromisedFilesOfTypes:(NSArray *)typeArray fromRect:(NSRect)aRect source:(id)sourceObject slideBack:(BOOL)slideBack event:(NSEvent *)theEvent

Parameters

typeArray

An array of file types being promised. The array elements can consist of file extensions and HFS types encoded with the NSFileTypeForHFSTypeCode function. If promising a directory of files, only include the top directory in the array.

aRect

A rectangle that describes the position of the icon in the receiver’s coordinate system.

sourceObject

An object that serves as the controller of the dragging operation. It must conform to the NSDraggingSource informal protocol, and is typically the receiver itself or its NSWindow object.

slideBack

A Boolean that indicates whether the icon being dragged should slide back to its position in the receiver if the file isn’t accepted. The icon slides back to aRect if slideBack is YES, the promised files are not accepted by the dragging destination, and the user has not disabled icon animation; otherwise it simply disappears.

theEvent

The mouse-down event object from which to initiate the drag operation. In particular, its mouse location is used for the offset of the icon being dragged.

Return Value

YES if the drag operation is initiated successfully, NO otherwise.

Discussion

This method must be invoked only within an implementation of the mouseDown: method. As part of its implementation, this method invokes dragImage:at:offset:event:pasteboard:source:slideBack:.

Promised files are files that do not exist, yet, but that the drag source, sourceObject, promises to create at a file system location specified by the drag destination when the drag is successfully dropped.

See Drag and Drop Programming Topics for Cocoa for more information on dragging operations.

Availability

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

See Also

• – dragImage:at:offset:event:pasteboard:source:slideBack:
• – shouldDelayWindowOrderingForEvent:

Declared In

drawPageBorderWithSize:

Allows applications that use the Application Kit pagination facility to draw additional marks on each logical page.

- (void)drawPageBorderWithSize:(NSSize)borderSize

Parameters

borderSize

An NSSize structure that defines a logical page.

Discussion

The marks can be such things as alignment marks or a virtual sheet border of size borderSize. The default implementation doesn’t draw anything.

Availability

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

See Also

• – drawSheetBorderWithSize:

Declared In

drawRect:

Overridden by subclasses to draw the receiver’s image within the passed-in rectangle.

- (void)drawRect:(NSRect)dirtyRect

Parameters

aRect

A rectangle defining the dirty area of the view that requires redrawing.

Discussion

The receiver can assume the focus has been locked and the coordinate transformations of its frame and bounds rectangles have been applied; all it needs to do is invoke rendering client functions.

You can avoid unnecessary drawing by paying attention to the dirtyRect parameter which defines the area that must be redrawn. The bounds of the entire view, as opposed to the dirty region, is given by [self bounds].

On Mac OS X version 10.2 and earlier, the Application Kit automatically clips any drawing you perform in this method to this rectangle. On Mac OS X version 10.3 and later, the Application Kit automatically clips drawing to a list of non-overlapping rectangles that more rigorously specify the area needing drawing. You can invoke the getRectsBeingDrawn:count: method to retrieve this list of rectangles and use them to constrain your drawing more tightly, if you wish. Moreover, the needsToDrawRect: method gives you a convenient way to test individual objects for intersection with the rectangles in the list. See Cocoa Drawing Guide for information and references on drawing.

The default implementation does nothing. If your custom view is a direct NSView subclass you do not need to call super's implementation.

Availability

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

See Also

• – display
• – getRectsBeingDrawn:count:
• – isFlipped
• – needsToDrawRect:
• – setNeedsDisplayInRect:
• – shouldDrawColor

Related Sample Code

• QTCoreVideo102
• QTCoreVideo103
• QTCoreVideo201
• QTCoreVideo301
• WebKitDOMElementPlugIn

Declared In

drawSheetBorderWithSize:

Allows applications that use the Application Kit pagination facility to draw additional marks on each printed sheet.

- (void)drawSheetBorderWithSize:(NSSize)borderSize

Parameters

borderSize

An NSSize structure that defines a printed sheet.

Discussion

The marks can be such things as crop marks or fold lines of size borderSize. This method has been deprecated.

Availability

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

See Also

• – drawPageBorderWithSize:

Declared In

enclosingMenuItem

Returns the menu item containing the receiver or any of its superviews in the view hierarchy.

- (NSMenuItem *)enclosingMenuItem

Return Value

Returns the menu item containing the receiver or any of its superviews in the view hierarchy, or nil if the receiver's view hierarchy is not in a menu item

Availability

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

Declared In

enclosingScrollView

Returns the nearest ancestor NSScrollView object containing the receiver (not including the receiver itself); otherwise returns nil.

- (NSScrollView *)enclosingScrollView

Availability

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

Related Sample Code

• CIAnnotation
• CITransitionSelectorSample2
• Sketch-112

Declared In

endDocument

This method is invoked at the end of the printing session.

- (void)endDocument

Discussion

If you override this method, call the superclass implementation.

Availability

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

Declared In

endPage

Writes the end of a conforming page.

- (void)endPage

Discussion

This method is invoked after each page is printed. It invokes unlockFocus. This method also generates comments for the bounding box and page fonts, if they were specified as being at the end of the page.

Availability

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

Declared In

enterFullScreenMode:withOptions:

Sets the receiver to full screen mode.

- (BOOL)enterFullScreenMode:(NSScreen *)screen withOptions:(NSDictionary *)options

Parameters

screen

The screen the receiver should cover.

options

A dictionary of options for the mode. For possible keys, see “Full screen mode”.

Return Value

YES if the receiver was able to enter full screen mode, otherwise NO.

Availability

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

Declared In

exitFullScreenModeWithOptions:

Instructs the receiver to exit full screen mode.

- (void)exitFullScreenModeWithOptions:(NSDictionary *)options

Parameters

options

A dictionary of options for the mode. For possible keys, see “Full screen mode”.

Availability

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

Declared In

focusRingType

Returns the type of focus ring drawn around the receiver.

- (NSFocusRingType)focusRingType

Return Value

An enum constant identifying a type of focus ring. Possible values are listed in NSFocusRingType.

Discussion

You can disable a view’s drawing of its focus ring by overriding this method to return NSFocusRingTypeNone, or by invoking setFocusRingType: with and argument of NSFocusRingTypeNone. You should only disable the default drawing of a view’s focus ring if you want it to draw its own focus ring (for example, setting the background color of the view), or if the view does not have sufficient space to display a focus ring.

Availability

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

See Also

• – setFocusRingType:

Declared In

frame

Returns the receiver’s frame rectangle, which defines its position in its superview.

- (NSRect)frame

Discussion

The frame rectangle may be rotated; use the frameRotation method to check this.

Availability

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

See Also

• – bounds
• – setFrame:

Related Sample Code

• MyPhoto
• Quartz Composer QCTV
• Quartz Composer WWDC 2005 TextEdit
• Reducer
• TextEditPlus

Declared In

frameCenterRotation

Returns the receiver’s rotation about the layer’s position.

- (CGFloat)frameCenterRotation

Return Value

The angle of rotatation of the frame around the center of the receiver.

Discussion

If the application has altered the layer’s anchorPoint property, the behavior is undefined. Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

frameRotation

Returns the angle, in degrees, of the receiver’s frame relative to its superview’s coordinate system.

- (CGFloat)frameRotation

Availability

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

See Also

• – setFrameRotation:
• – boundsRotation

Declared In

getRectsBeingDrawn:count:

Returns by indirection a list of non-overlapping rectangles that define the area the receiver is being asked to draw in drawRect:.

- (void)getRectsBeingDrawn:(const NSRect **)rects count:(NSInteger *)count

Parameters

rects

On return, contains a list of non-overlapping rectangles defining areas to be drawn in. The rectangles returned in rects are in the coordinate space of the receiver.

count

On return, the number of rectangles in the rects list.

Discussion

An implementation of drawRect: can use this information to test whether objects or regions within the view intersect with the rectangles in the list, and thereby avoid unnecessary drawing that would be completely clipped away.

The needsToDrawRect: method gives you a convenient way to test individual objects for intersection with the area being drawn in drawRect:. However, you may want to retrieve and directly inspect the rectangle list if this is a more efficient way to perform intersection testing.

You should send this message only from within a drawRect: implementation. The aRect parameter of drawRect: is the rectangle enclosing the returned list of rectangles; you can use it in an initial pass to reject objects that are clearly outside the area to be drawn.

Availability

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

See Also

• – wantsDefaultClipping

Declared In

getRectsExposedDuringLiveResize:count:

Returns a list of rectangles indicating the newly exposed areas of the receiver.

- (void)getRectsExposedDuringLiveResize:(NSRect)exposedRects count:(NSInteger *)count

Parameters

exposedRects

On return, contains the list of rectangles. The returned rectangles are in the coordinate space of the receiver.

count

Contains the number of rectangles in exposedRects; this value may be 0 and is guaranteed to be no more than 4.

Discussion

If your view does not support content preservation during live resizing, the entire area of your view is returned in the exposedRects parameter. To support content preservation, override preservesContentDuringLiveResize in your view and have your implementation return YES.

If the view decreased in both height and width, the list of returned rectangles will be empty. If the view increased in both height and width and its upper-left corner stayed anchored in the same position, the list of returned rectangles will contain a vertical and horizontal component indicating the exposed area.

Availability

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

See Also

• – preservesContentDuringLiveResize
• – rectPreservedDuringLiveResize

Declared In

gState

Returns the identifier for the receiver’s graphics state object, or 0 if the receiver doesn’t have a graphics state object.

- (NSInteger)gState

Discussion

A view object’s graphics state object is recreated from scratch whenever the view is focused, unless the allocateGState method has been invoked. So if the receiver hasn’t been focused or hasn’t received the allocateGState message, this method returns 0.

Although applications rarely need to use the value returned by gState, it can be passed to the few methods that take an object identifier as a parameter.

Availability

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

See Also

• – allocateGState
• – setUpGState
• – renewGState
• – releaseGState
• – lockFocus

Declared In

heightAdjustLimit

Returns the fraction (from 0.0 to 1.0) of the page that can be pushed onto the next page during automatic pagination to prevent items such as lines of text from being divided across pages.

- (CGFloat)heightAdjustLimit

Discussion

This fraction is used to calculate the bottom edge limit for an adjustPageHeightNew:top:bottom:limit: message.

Availability

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

See Also

• – widthAdjustLimit

Declared In

hitTest:

Returns the farthest descendant of the receiver in the view hierarchy (including itself) that contains a specified point, or nil if that point lies completely outside the receiver.

- (NSView *)hitTest:(NSPoint)aPoint

Parameters

aPoint

A point that is in the coordinate system of the receiver’s superview, not of the receiver itself.

Return Value

A view object that is the farthest descendent of aPoint.

Discussion

This method is used primarily by an NSWindow object to determine which view should receive a mouse-down event. You’d rarely need to invoke this method, but you might want to override it to have a view object hide mouse-down events from its subviews. This method ignores hidden views.

Availability

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

See Also

• – mouse:inRect:
• – convertPoint:toView:
• – setHidden:

Declared In

initWithFrame:

Initializes and returns a newly allocated NSView object with a specified frame rectangle.

- (id)initWithFrame:(NSRect)frameRect

Parameters

frameRect

The frame rectangle for the created view object.

Return Value

An initialized NSView object or nil if the object couldn't be created.

Discussion

The new view object must be inserted into the view hierarchy of a window before it can be used. This method is the designated initializer for the NSView class. Returns an initialized object.

Availability

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

See Also

• – addSubview:
• – addSubview:positioned:relativeTo:
• – setFrame:

Declared In

inLiveResize

A convenience method, expected to be called from drawRect:, to assist in decisions about optimized drawing.

- (BOOL)inLiveResize

Return Value

YES if the receiver is in a live-resize operation, NO otherwise.

Availability

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

See Also

• – viewDidEndLiveResize
• – viewWillStartLiveResize

Related Sample Code

• GLChildWindowDemo
• NSGLImage
• OpenGL Screensaver
• WhackedTV

Declared In

isDescendantOf:

Returns YES if the receiver is a subview of a given view or if it’s identical to that view; otherwise, it returns NO.

- (BOOL)isDescendantOf:(NSView *)aView

Parameters

aView

The view to test for subview relationship within the view hierarchy.

Discussion

The method returns YES if the receiver is either an immediate or distant subview of aView.

Availability

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

See Also

• – superview
• – subviews
• – ancestorSharedWithView:

Declared In

isFlipped

Returns YES if the receiver uses flipped drawing coordinates or NO if it uses native coordinates.

- (BOOL)isFlipped

Discussion

The default implementation returns NO; subclasses that use flipped coordinates should override this method to return YES.

Availability

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

Related Sample Code

• ImageMapExample
• Quartz Composer QCTV
• Quartz Composer WWDC 2005 TextEdit
• Sketch-112
• TextEditPlus

Declared In

isHidden

Returns whether the receiver is marked as hidden.

- (BOOL)isHidden

Discussion

The return value reflects the state of the receiver only, as set in Interface Builder or through the most recent setHidden: message, and does not account for the state of the receiver’s ancestors in the view hierarchy, Thus this method returns NO when the receiver is effectively hidden because it has a hidden ancestor. See setHidden: for a discussion of the mechanics and implications of hidden views.

If you want to determine whether a view is effectively hidden, for whatever reason, send the isHiddenOrHasHiddenAncestor to the view instead.

Availability

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

Related Sample Code

• GLSLShowpiece

Declared In

isHiddenOrHasHiddenAncestor

Returns YES if the receiver is marked as hidden or has an ancestor in the view hierarchy that is marked as hidden; returns NO otherwise.

- (BOOL)isHiddenOrHasHiddenAncestor

Discussion

The return value reflects state set through the setHidden: method in the receiver of one of its ancestors in the view hierarchy. It does not account for other reasons why a view might be considered hidden, such as being positioned outside its superview’s bounds, not having a window, or residing in a window that is offscreen or overlapped by another window.

Availability

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

See Also

• – isHidden

Declared In

isInFullScreenMode

Returns a Boolean value that indicates whether the receiver is in full screen mode.

- (BOOL)isInFullScreenMode

Return Value

YES if the receiver is in full screen mode, otherwise NO.

Availability

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

Declared In

isOpaque

Overridden by subclasses to return YES if the receiver is opaque, NO otherwise.

- (BOOL)isOpaque

Discussion

A view object is opaque if it completely covers its frame rectangle when drawing itself. The default implementation performs no drawing at all and so returns NO.

Availability

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

See Also

• – opaqueAncestor
• – displayRectIgnoringOpacity:
• – displayIfNeededIgnoringOpacity
• – displayIfNeededInRectIgnoringOpacity:

Related Sample Code

• GLChildWindowDemo
• Quartz Composer WWDC 2005 TextEdit
• Sketch-112
• TextEditPlus
• WhackedTV

Declared In

isRotatedFromBase

Returns YES if the receiver or any of its ancestors has ever received a setFrameRotation: or setBoundsRotation: message; otherwise returns NO.

- (BOOL)isRotatedFromBase

Discussion

The intent of this information is to optimize drawing and coordinate calculation, not necessarily to reflect the exact state of the receiver’s coordinate system, so it may not reflect the actual rotation. For example, if an NSView object is rotated to 45 degrees and later back to 0, this method still returns YES.

Availability

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

See Also

• – frameRotation
• – boundsRotation

Declared In

isRotatedOrScaledFromBase

Returns YES if the receiver or any of its ancestors has ever had a nonzero frame or bounds rotation, or has been scaled from the window’s base coordinate system; otherwise returns NO.

- (BOOL)isRotatedOrScaledFromBase

Discussion

The intent of this information is to optimize drawing and coordinate calculation, not necessarily to reflect the exact state of the receiver’s coordinate system, so it may not reflect the actual rotation or scaling. For example, if an NSView object is rotated to 45 degrees and later back to 0, this method still returns YES.

Availability

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

See Also

• – frameRotation
• – boundsRotation
• – centerScanRect:
• – setBounds:
• – setBoundsSize:
• – scaleUnitSquareToSize:

Declared In

knowsPageRange:

Returns YES if the receiver handles page boundaries, NO otherwise.

- (BOOL)knowsPageRange:(NSRangePointer)aRange

Parameters

aRange

On return, holds the page range if YES is returned directly. Page numbers are one-based—that is pages run from one to N.

Discussion

Returns NO if the receiver uses the default auto-pagination mechanism. The default implementation returns NO. Override this method if your class handles page boundaries.

Availability

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

Declared In

layer

Returns the Core Animation layer that the receiver as its backing store.

- (CALayer *)layer

Return Value

The Core Animation layer the receiver is using as its backing store.

Availability

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

Related Sample Code

• CALayerEssentials
• OpenGLCompositorLab

Declared In

locationOfPrintRect:

Invoked by print: to determine the location of the region of the receiver being printed on the physical page.

- (NSPoint)locationOfPrintRect:(NSRect)aRect

Parameters

aRect

A rectangle defining a region of the receiver; it is expressed in the default coordinate system of the page.

Return Value

A point to be used for setting the origin for aRect, whose size the receiver can examine in order to properly place it. It is expressed in the default coordinate system of the page.

Discussion

The default implementation places aRect according to the status of the NSPrintInfo object for the print job. By default it places the image in the upper-left corner of the page, but if the NSPrintInfo methods isHorizontallyCentered or isVerticallyCentered return YES, it centers a single-page image along the appropriate axis. A multiple-page document, however, is always placed so the divided pieces can be assembled at their edges.

Availability

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

Declared In

lockFocus

Locks the focus on the receiver, so subsequent commands take effect in the receiver’s window and coordinate system.

- (void)lockFocus

Discussion

If you don’t use a display... method to draw an NSView object, you must invoke lockFocus before invoking methods that send commands to the window server, and must balance it with an unlockFocus message when finished.

Hiding or miniaturizing a one-shot window causes the backing store for that window to be released. If you don’t use the standard display mechanism to draw, you should use lockFocusIfCanDraw rather than lockFocus if there is a chance of drawing while the window is either miniaturized or hidden.

Availability

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

See Also

• + focusView
• – display
• – drawRect:
• – lockFocusIfCanDraw

Related Sample Code

• MungSaver
• QTKitFrameStepper
• VideoViewer

Declared In

lockFocusIfCanDraw

Locks the focus to the receiver atomically if the canDraw method returns YES and returns the value of canDraw.

- (BOOL)lockFocusIfCanDraw

Discussion

Your thread will not be preempted by other threads between the canDraw method and the lock. This method fails to lock focus and returns NO, when the receiver is hidden and the current context is drawing to the screen (as opposed to a printing context).

Availability

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

Related Sample Code

• VideoViewer

Declared In

lockFocusIfCanDrawInContext:

Locks the focus to the receiver atomically if drawing can occur in the specified graphics context.

- (BOOL)lockFocusIfCanDrawInContext:(NSGraphicsContext *)context

Parameters

context

The graphics context in which drawing might occur. See the discussion for the implications of the type of context.

Return Value

YES if successful; otherwise, returns NO.

Discussion

Your thread will not be preempted by other threads between the canDraw method and the lock.

If the context parameter represents the context for the window containing the view, then all of the necessary transformations are applied. This includes the application of the receiver’s bounds and frame transforms along with any transforms it inherited from its ancestors. If context specifies any other graphics context, then only the receiver’s bounds transform is applied.

Special Considerations

Availability

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

See Also

• – lockFocus
• – lockFocusIfCanDraw

Declared In

menuForEvent:

Overridden by subclasses to return a context-sensitive pop-up menu for a given mouse-down event.

- (NSMenu *)menuForEvent:(NSEvent *)theEvent

Parameters

theEvent

An object representing a mouse-down event.

Discussion

The receiver can use information in the mouse event, such as its location over a particular element of the receiver, to determine what kind of menu to return. For example, a text object might display a text-editing menu when the cursor lies over text and a menu for changing graphics attributes when the cursor lies over an embedded image.

The default implementation returns the receiver’s normal menu.

Availability

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

See Also

• + defaultMenu
• – menu (NSResponder)

Declared In

mouse:inRect:

Returns whether a region of the receiver contains a specified point, accounting for whether the receiver is flipped or not.

- (BOOL)mouse:(NSPoint)aPoint inRect:(NSRect)aRect

Parameters

aPoint

A point that is expressed in the receiver's coordinate system. This point generally represents the hot spot of the mouse cursor.

aRect

A rectangle that is expressed in the receiver’s coordinate system.

Return Value

YES if aRect contains aPoint, NO otherwise.

Discussion

Point-in-rectangle functions generally assume that the bottom edge of a rectangle is outside of the rectangle boundaries, while the upper edge is inside the boundaries. This method views aRect from the point of view of the user—that is, this method always treats the bottom edge of the rectangle as the one closest to the bottom edge of the user’s screen. By making this adjustment, this function ensures consistent mouse-detection behavior from the user’s perspective.

Never use the Foundation’s NSPointInRect function as a substitute for this method. It doesn’t account for flipped coordinate systems.

Availability

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

See Also

• – hitTest:
• – isFlipped
• NSMouseInRect (Foundation functions)
• – convertPoint:fromView:

Declared In

mouseDownCanMoveWindow

Returns YES if the receiver does not need to handle a mouse down and can pass it through to superviews; NO if it needs to handle the mouse down.

- (BOOL)mouseDownCanMoveWindow

Discussion

This allows iApp-type applications to determine the region by which a window can be moved. By default, this method returns NO if the view is opaque; otherwise, it returns YES. Subclasses can override this method to return a different value.

Availability

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

Related Sample Code

• DockTile
• SpeedometerView
• WebKitPluginStarter
• WebKitPluginWithJavaScript

Declared In

needsDisplay

Returns YES if the receiver needs to be displayed, as indicated using setNeedsDisplay: and setNeedsDisplayInRect:; returns NO otherwise.

- (BOOL)needsDisplay

Discussion

The displayIfNeeded... methods check this status to avoid unnecessary drawing, and all display methods clear this status to indicate that the view object is up to date.

Availability

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

Declared In

needsPanelToBecomeKey

Overridden by subclasses to return YES if the receiver requires its panel, which might otherwise avoid becoming key, to become the key window so that it can handle keyboard input.

- (BOOL)needsPanelToBecomeKey

Discussion

Such a subclass should also override acceptsFirstResponder to return YES. The default implementation returns NO.

Availability

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

See Also

• – becomesKeyOnlyIfNeeded (NSPanel)

Related Sample Code

• Clock Control

Declared In

needsToDrawRect:

Returns whether the specified rectangle intersects any part of the area that the receiver is being asked to draw.

- (BOOL)needsToDrawRect:(NSRect)aRect

Parameters

aRect

A rectangle defining a region of the receiver.

Discussion

You typically send this message from within a drawRect: implementation. It gives you a convenient way to determine whether any part of a given graphical entity might need to be drawn. It is optimized to efficiently reject any rectangle that lies outside the bounding box of the area the receiver is being asked to draw in drawRect:.

Availability

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

Declared In

nextKeyView

Returns the view object following the receiver in the key view loop, or nil if there is none.

- (NSView *)nextKeyView

Discussion

This view should, if possible, be made first responder when the user navigates forward from the receiver using keyboard interface control.

Availability

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

See Also

• – nextValidKeyView
• – setNextKeyView:
• – previousKeyView
• – previousValidKeyView
• – selectNextKeyView: (NSWindow)
• – selectKeyViewFollowingView: (NSWindow)
• – selectPreviousKeyView: (NSWindow)
• – selectKeyViewPrecedingView: (NSWindow)

Related Sample Code

• TrackBall

Declared In

nextValidKeyView

Returns the closest view object in the key view loop that follows the receiver and actually accepts first responder status, or nil if there is none.

- (NSView *)nextValidKeyView

Discussion

This method ignores hidden views when it determines the next valid key view.

Availability

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

See Also

• – nextKeyView
• – setNextKeyView:
• – previousKeyView
• – previousValidKeyView
• – selectNextKeyView: (NSWindow)
• – selectKeyViewFollowingView: (NSWindow)
• – selectPreviousKeyView: (NSWindow)
• – selectKeyViewPrecedingView: (NSWindow)
• – setHidden:

Declared In

opaqueAncestor

Returns the receiver’s closest opaque ancestor (including the receiver itself).

- (NSView *)opaqueAncestor

Availability

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

See Also

• – isOpaque
• – displayRectIgnoringOpacity:
• – displayIfNeededIgnoringOpacity
• – displayIfNeededInRectIgnoringOpacity:

Declared In

pageFooter

Returns a default footer string that includes the current page number and page count.

- (NSAttributedString *)pageFooter

Discussion

A printable view class can override this method to substitute its own content in place of the default value. You should not need to call this method directly. The printing system calls it once per page during printing.

Footers are generated only if the user defaults contain the key NSPrintHeaderAndFooter with the value YES.

Availability

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

See Also

• – pageHeader

Declared In

pageHeader

Returns a default header string that includes the print job title and date.

- (NSAttributedString *)pageHeader

Discussion

Typically, the print job title is the same as the window title. A printable view class can override this method to substitute its own content in place of the default value. You should not need to call this method directly. The printing system calls it once per page during printing.

Headers are generated only if the user defaults contain the key NSPrintHeaderAndFooter with the value YES.

Availability

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

See Also

• – pageFooter

Declared In

performKeyEquivalent:

Implemented by subclasses to respond to key equivalents (also known as keyboard shortcuts).

- (BOOL)performKeyEquivalent:(NSEvent *)theEvent

Parameters

theEvent

The key-down event object representing a key equivalent.

Return Value

YES if theEvent is a key equivalent that the receiver handled, NO if it is not a key equivalent that it should handle.

Discussion

If the receiver’s key equivalent is the same as the characters of the key-down event theEvent, as returned by charactersIgnoringModifiers, the receiver should take the appropriate action and return YES. Otherwise, it should return the result of invoking super’s implementation. The default implementation of this method simply passes the message down the view hierarchy (from superviews to subviews) and returns NO if none of the receiver’s subviews responds YES.

Availability

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

See Also

• – performMnemonic:
• – keyDown: (NSWindow)

Declared In

performMnemonic:

Implemented by subclasses to respond to mnemonics.

- (BOOL)performMnemonic:(NSString *)aString

Parameters

aString

A string representing the mnemonic to handle.

Discussion

If the receiver’s mnemonic is the same as the characters of the string aString, the receiver should take the appropriate action and return YES. Otherwise, it should return the result of invoking super’s implementation. The default implementation of this method simply passes the message down the view hierarchy (from superviews to subviews) and returns NO if none of the receiver’s subviews responds YES. Mnemonics are not supported in Mac OS X.

Availability

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

See Also

• – performKeyEquivalent:
• – keyDown: (NSWindow)

Declared In

postsBoundsChangedNotifications

Returns YES if the receiver posts notifications to the default notification center whenever its bounds rectangle changes; returns NO otherwise.

- (BOOL)postsBoundsChangedNotifications

Discussion

See setPostsBoundsChangedNotifications: for a list of methods that result in notifications.

Availability

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

Declared In

postsFrameChangedNotifications

Returns YES if the receiver posts notifications to the default notification center whenever its frame rectangle changes; returns NO otherwise.

- (BOOL)postsFrameChangedNotifications

Discussion

See setPostsBoundsChangedNotifications: for a list of methods that result in notifications.

Availability

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

Declared In

preservesContentDuringLiveResize

Returns YES if the view supports the optimization of live-resize operations by preserving content that has not moved; otherwise, returns NO.

- (BOOL)preservesContentDuringLiveResize

Discussion

The default is NO. If your view supports the content preservation feature, you should override this method and have your implementation return YES.

Content preservation lets your view decide what to redraw during a live resize operation. If your view supports this feature, you should also provide a custom implementation of setFrameSize: that invalidates the portions of your view that actually need to be redrawn.

For information on how to implement this feature in your views, see Cocoa Performance Guidelines.

Availability

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

See Also

• – setFrameSize:

Declared In

previousKeyView

Returns the view object preceding the receiver in the key view loop, or nil if there is none.

- (NSView *)previousKeyView

Discussion

This view should, if possible, be made first responder when the user navigates backward from the receiver using keyboard interface control.

Availability

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

See Also

• – previousValidKeyView
• – nextKeyView
• – nextValidKeyView
• – setNextKeyView:
• – selectNextKeyView: (NSWindow)
• – selectKeyViewFollowingView: (NSWindow)
• – selectPreviousKeyView: (NSWindow)
• – selectKeyViewPrecedingView: (NSWindow)

Declared In

previousValidKeyView

Returns the closest view object in the key view loop that precedes the receiver and actually accepts first responder status, or nil if there is none.

- (NSView *)previousValidKeyView

Discussion

This method ignores hidden views when it determines the previous valid key view.

Availability

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

See Also

• – previousKeyView
• – nextValidKeyView
• – nextKeyView
• – setNextKeyView:
• – selectNextKeyView: (NSWindow)
• – selectKeyViewFollowingView: (NSWindow)
• – selectPreviousKeyView: (NSWindow)
• – selectKeyViewPrecedingView: (NSWindow)
• – setHidden:

Declared In

print:

This action method opens the Print panel, and if the user chooses an option other than canceling, prints the receiver and all its subviews to the device specified in the Print panel.

- (void)print:(id)sender

Parameters

sender

The object that sent the message.

Availability

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

See Also

• – dataWithEPSInsideRect:
• – writeEPSInsideRect:toPasteboard:

Declared In

printJobTitle

Returns the receiver’s print job title.

- (NSString *)printJobTitle

Discussion

The default implementation first tries the window’s NSDocument display name (displayName), then the window’s title.

Availability

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

Declared In

rectForPage:

Implemented by subclasses to determine the portion of the receiver to be printed for the page number page.

- (NSRect)rectForPage:(NSInteger)pageNumber

Parameters

pageNumber

An integer indicating a page number. Page numbers are one-based—that is pages run from one to N.

Return Value

A rectangle defining the region of the receiver to be printed for pageNumber. This method returns NSZeroRect if pageNumber is outside the receiver’s bounds.

Discussion

If the receiver responded YES to an earlier knowsPageRange: message, this method is invoked for each page it specified in the out parameters of that message. The receiver is later made to display this rectangle in order to generate the image for this page.

If an NSView object responds NO to knowsPageRange:, this method isn’t invoked by the printing mechanism.

Availability

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

See Also

• – adjustPageHeightNew:top:bottom:limit:
• – adjustPageWidthNew:left:right:limit:

Declared In

rectPreservedDuringLiveResize

Returns the rectangle identifying the portion of your view that did not change during a live resize operation.

- (NSRect)rectPreservedDuringLiveResize

Discussion

The returned rectangle is in the coordinate system of your view and reflects the space your view previously occupied. This rectangle may be smaller or the same size as your view’s current bounds, depending on whether the view grew or shrunk.

If your view does not support content preservation during live resizing, the returned rectangle will be empty. To support content preservation, override preservesContentDuringLiveResize in your view and have your implementation return YES.

Availability

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

See Also

• – getRectsExposedDuringLiveResize:count:
• – preservesContentDuringLiveResize

Declared In

reflectScrolledClipView:

Notifies a clip view’s superview that either the clip view’s bounds rectangle or the document view’s frame rectangle has changed, and that any indicators of the scroll position need to be adjusted.

- (void)reflectScrolledClipView:(NSClipView *)aClipView

Parameters

aClipView

The NSClipView object whose superview is to be notified.

Discussion

NSScrollView implements this method to update its NSScroller objects.

Availability

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

Declared In

registeredDraggedTypes

Returns the array of pasteboard drag types that the view can accept.

- (NSArray *)registeredDraggedTypes

Discussion

This method returns the types registered by calling registerForDraggedTypes:. Each element of the array is a global string constant; see "Constants" for descriptions of the pasteboard string constants. The returned elements are in no particular order, but the array is guaranteed not to contain duplicate entries.

Availability

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

Declared In

registerForDraggedTypes:

Registers the pasteboard types that the receiver will accept as the destination of an image-dragging session.

- (void)registerForDraggedTypes:(NSArray *)pboardTypes

Parameters

pboardTypes

An array of pasteboard types, each a global string constant. See "Constants" for descriptions of the pasteboard string constants.

Discussion

Registering an NSView object for dragged types automatically makes it a candidate destination object for a dragging session. As such, it must properly implement some or all of the NSDraggingDestination protocol methods. As a convenience, NSView provides default implementations of these methods. See the NSDraggingDestination protocol specification for details.

Availability

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

See Also

• – registeredDraggedTypes
• – unregisterDraggedTypes

Declared In

releaseGState

Frees the receiver’s graphics state object, if it has one.

- (void)releaseGState

Availability

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

See Also

• – allocateGState

Declared In

removeAllToolTips

Removes all tool tips assigned to the receiver.

- (void)removeAllToolTips

Discussion

This method operates on tool tips created using either addToolTipRect:owner:userData: or setToolTip:.

Availability

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

Declared In

removeCursorRect:cursor:

Completely removes a cursor rectangle from the receiver.

- (void)removeCursorRect:(NSRect)aRect cursor:(NSCursor *)aCursor

Parameters

aRect

A rectangle defining a region of the receiver. Must match a value previously specified using addCursorRect:cursor:.

aCursor

An object representing a cursor. Must match a value previously specified using addCursorRect:cursor:.

Discussion

You should rarely need to use this method. resetCursorRects, which is invoked any time cursor rectangles need to be rebuilt, should establish only the cursor rectangles needed. If you implement resetCursorRects in this way, you can then simply modify the state that resetCursorRects uses to build its cursor rectangles and then invoke the NSWindow method invalidateCursorRectsForView:.

Availability

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

See Also

• – discardCursorRects

Declared In

removeFromSuperview

Unlinks the receiver from its superview and its window, removes it from the responder chain, and invalidates its cursor rectangles.

- (void)removeFromSuperview

Discussion

The receiver is also 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 as a subview of another NSView.

Never invoke this method during display.

Availability

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

See Also

• – addSubview:
• – addSubview:positioned:relativeTo:
• – removeFromSuperviewWithoutNeedingDisplay

Related Sample Code

• FancyAbout
• GLChildWindowDemo
• Quartz Composer WWDC 2005 TextEdit
• Sketch-112
• TextEditPlus

Declared In

removeFromSuperviewWithoutNeedingDisplay

Unlinks the receiver from its superview and its window and removes it from the responder chain, but does not invalidate its cursor rectangles to cause redrawing.

- (void)removeFromSuperviewWithoutNeedingDisplay

Discussion

The receiver is also 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 as a subview of another view.

Unlike its counterpart, removeFromSuperview, this method can be safely invoked during display.

Availability

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

See Also

• – addSubview:
• – addSubview:positioned:relativeTo:

Related Sample Code

• CoreRecipes

Declared In

removeToolTip:

Removes the tool tip identified by specified tag.

- (void)removeToolTip:(NSToolTipTag)tag

Parameters

tag

An integer tag that is the value returned by a previous addToolTipRect:owner:userData: message.

Availability

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

Declared In

removeTrackingArea:

Removes a given tracking area from the receiver.

- (void)removeTrackingArea:(NSTrackingArea *)trackingArea

Parameters

trackingArea

The tracking area to remove from the receiver.

Availability

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

Declared In

removeTrackingRect:

Removes the tracking rectangle identified by a tag.

- (void)removeTrackingRect:(NSTrackingRectTag)aTag

Parameters

aTag

An integer value identifying a tracking rectangle. It was returned by a previously sent addTrackingRect:owner:userData:assumeInside: message.

Availability

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

See Also

• – addTrackingRect:owner:userData:assumeInside:
• – removeTrackingArea:

Declared In

renewGState

Invalidates the receiver’s graphics state object, if it has one.

- (void)renewGState

Discussion

The receiver's graphics state object will be regenerated using setUpGState the next time the receiver is focused for drawing

Availability

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

See Also

• – lockFocus

Related Sample Code

• GLSLShowpiece
• VideoViewer

Declared In

replaceSubview:with:

Replaces one of the receiver’s subviews with another view.

- (void)replaceSubview:(NSView *)oldView with:(NSView *)newView

Parameters

oldView

The view to be replaced by newView. May not be nil.

newView

The view to replace oldView. May not be nil.

Discussion

This method does nothing if oldView is not a subview of the receiver.

Neither oldView nor newView may be nil, and the behavior is undefined if either of these parameters is nil.

This method causes oldView 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 as a subview of another NSView.

Availability

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

See Also

• – addSubview:
• – addSubview:positioned:relativeTo:

Declared In

resetCursorRects

Overridden by subclasses to define their default cursor rectangles.

- (void)resetCursorRects

Discussion

A subclass’s implementation must invoke addCursorRect:cursor: for each cursor rectangle it wants to establish. The default implementation does nothing.

Application code should never invoke this method directly; it’s invoked automatically as described in "Handling Tracking-Rectangle and Cursor-Update Events in Views." Use the invalidateCursorRectsForView: method instead to explicitly rebuild cursor rectangles.

Availability

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

See Also

• – visibleRect

Related Sample Code

• TextLinks

Declared In

resizeSubviewsWithOldSize:

Informs the receiver’s subviews that the receiver’s bounds rectangle size has changed.

- (void)resizeSubviewsWithOldSize:(NSSize)oldBoundsSize

Parameters

oldBoundsSize

The previous size of the receiver's bounds rectangle.

Discussion

If the receiver is configured to autoresize its subviews, this method is automatically invoked by any method that changes the receiver’s frame size.

The default implementation sends resizeWithOldSuperviewSize: to the receiver’s subviews with oldBoundsSize as the argument. You shouldn’t invoke this method directly, but you can override it to define a specific retiling behavior.

Availability

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

See Also

• – setAutoresizesSubviews:

Declared In

resizeWithOldSuperviewSize:

Informs the receiver that the bounds size of its superview has changed.

- (void)resizeWithOldSuperviewSize:(NSSize)oldBoundsSize

Parameters

oldBoundsSize

The previous size of the superview's bounds rectangle.

Discussion

This method is normally invoked automatically from resizeSubviewsWithOldSize:.

The default implementation resizes the receiver according to the autoresizing options listed under the setAutoresizingMask: method description. You shouldn’t invoke this method directly, but you can override it to define a specific resizing behavior.

Availability

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

Declared In

rotateByAngle:

Rotates the receiver’s bounds rectangle by a specified degree value around the origin of the coordinate system, (0.0, 0.0).

- (void)rotateByAngle:(CGFloat)angle

Parameters

angle

A float value specifying the angle of rotation, in degrees.

Discussion

See the setBoundsRotation: method description for more information. This method neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

This method posts an NSViewBoundsDidChangeNotification to the default notification center if the receiver is configured to do so.

Availability

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

See Also

• – setFrameRotation:
• – setPostsBoundsChangedNotifications:

Declared In

scaleUnitSquareToSize:

Scales the receiver’s coordinate system so that the unit square scales to the specified dimensions.

- (void)scaleUnitSquareToSize:(NSSize)newUnitSize

Parameters

newUnitSize

An NSSize structure specifying the new unit size.

Discussion

For example, a newUnitSize of (0.5, 1.0) causes the receiver’s horizontal coordinates to be halved, in turn doubling the width of its bounds rectangle. Note that scaling is performed from the origin of the coordinate system, (0.0, 0.0), not the origin of the bounds rectangle; as a result, both the origin and size of the bounds rectangle are changed. The frame rectangle remains unchanged.

This method neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

This method posts an NSViewBoundsDidChangeNotification to the default notification center if the receiver is configured to do so.

Availability

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

See Also

• – setBoundsSize:
• – setPostsBoundsChangedNotifications:

Declared In

scrollClipView:toPoint:

Notifies the superview of a clip view that the clip view needs to reset the origin of its bounds rectangle.

- (void)scrollClipView:(NSClipView *)aClipView toPoint:(NSPoint)newOrigin

Parameters

aClipView

The NSClipView object whose superview is to be notified.

newOrigin

A point that specifies the new origin of the clip view's bounds rectangle.

Discussion

The superview of aClipView should then send a scrollToPoint: message to aClipView with newOrigin as the argument. This mechanism is provided so the NSClipView object's superview can coordinate scrolling of multiple tiled clip views.

Availability

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

See Also

• – scrollToPoint: (NSClipView)

Declared In

scrollPoint:

Scrolls the receiver’s closest ancestor NSClipView object so a point in the receiver lies at the origin of the clip view's bounds rectangle.

- (void)scrollPoint:(NSPoint)aPoint

Parameters

aPoint

The point in the receiver to scroll to.

Availability

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

See Also

• – autoscroll:
• – scrollToPoint: (NSClipView)
• – isDescendantOf:

Declared In

scrollRect:by:

Copies the visible portion of the receiver’s rendered image within a region and lays that portion down again at a specified offset .

- (void)scrollRect:(NSRect)aRect by:(NSSize)offset

Parameters

aRect

A rectangle defining a region of the receiver.

offset

A NSSize structure that specifies an offset from from aRect’s origin.

Discussion

This method is useful during scrolling or translation of the coordinate system to efficiently move as much of the receiver’s rendered image as possible without requiring it to be redrawn, following these steps:

1. Invoke scrollRect:by: to copy the rendered image.

2. Move the view object’s origin or scroll it within its superview.

3. Calculate the newly exposed rectangles and invoke either setNeedsDisplay: or setNeedsDisplayInRect: to draw them.

You should rarely need to use this method, however. The scrollPoint:, scrollRectToVisible:, and autoscroll: methods automatically perform optimized scrolling.

Availability

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

See Also

• – setBoundsOrigin:
• – translateOriginToPoint:

Declared In

scrollRectToVisible:

Scrolls the receiver’s closest ancestor NSClipView object the minimum distance needed so a specified region of the receiver becomes visible in the clip view.

- (BOOL)scrollRectToVisible:(NSRect)aRect

Parameters

aRect

The rectangle to be made visible in the clip view.

Discussion

YES if any scrolling is performed; otherwise returns NO.

Availability

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

See Also

• – autoscroll:
• – scrollToPoint: (NSClipView)
• – isDescendantOf:

Related Sample Code

• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

setAlphaValue:

Sets the opacity of the receiver.

- (void)setAlphaValue:(CGFloat)viewAlpha

Parameters

viewAlpha

The desired opacity of the receiver.

Discussion

This method sets the value of the opacity property of the receiver’s layer. Possible values are between 0.0 (transparent) and 1.0 (opaque). The default is 1.0.

Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

setAutoresizesSubviews:

Determines whether the receiver automatically resizes its subviews when its frame size changes.

- (void)setAutoresizesSubviews:(BOOL)flag

Parameters

flag

If YES, the receiver invokes resizeSubviewsWithOldSize: whenever its frame size changes; if NO, it doesn’t.

Discussion

View objects do autoresize their subviews by default.

Availability

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

See Also

• – autoresizesSubviews

Declared In

setAutoresizingMask:

Determines how the receiver’s resizeWithOldSuperviewSize: method changes its frame rectangle.

- (void)setAutoresizingMask:(NSUInteger)mask

Parameters

mask

An integer bit mask. mask can be specified by combining using the C bitwise OR operator any of the options described in “Resizing masks”.

Discussion

Where more than one option along an axis is set, resizeWithOldSuperviewSize: by default distributes the size difference as evenly as possible among the flexible portions. For example, if NSViewWidthSizable and NSViewMaxXMargin are set and the superview’s width has increased by 10.0 units, the receiver’s frame and right margin are each widened by 5.0 units.

Availability

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

See Also

• – autoresizingMask
• – resizeSubviewsWithOldSize:
• – setAutoresizesSubviews:

Related Sample Code

• PredicateEditorSample
• Quartz Composer QCTV
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus
• WhackedTV

Declared In

setBackgroundFilters:

An array of CoreImage filters that are applied to the receiver’s background.

- (void)setBackgroundFilters:(NSArray *)filters

Parameters

filters

An array of CoreImage filters.

Discussion

This method sets the value of the backgroundFilters property of the receiver’s layer.

Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

setBounds:

Sets the receiver’s bounds rectangle.

- (void)setBounds:(NSRect)boundsRect

Parameters

boundsRect

A rectangle defining the new bounds of the receiver.

Discussion

The bounds rectangle determines the origin and scale of the receiver’s coordinate system within its frame rectangle. This method neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

This method posts an NSViewBoundsDidChangeNotification to the default notification center if the receiver is configured to do so.

After calling this method, NSView creates an internal transform (or appends these changes to an existing internal transform) to convert from frame coordinates to bounds coordinates in your view. As long as the width-to-height ratio of the two coordinate systems remains the same, your content appears normal. If the ratios differ, your content may appear skewed.

Availability

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

See Also

• – bounds
• – setBoundsRotation:
• – setBoundsOrigin:
• – setBoundsSize:
• – setFrame:
• – setPostsBoundsChangedNotifications:

Declared In

setBoundsOrigin:

Sets the origin of the receiver’s bounds rectangle to a specified point,

- (void)setBoundsOrigin:(NSPoint)newOrigin

Parameters

newOrigin

A point specifying the new bounds origin of the receiver.

Discussion

In setting the new bounds origin, this method effectively shifts the receiver's coordinate system so newOrigin lies at the origin of the receiver’s frame rectangle. It neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

This method posts an NSViewBoundsDidChangeNotification to the default notification center if the receiver is configured to do so.

After calling this method, NSView creates an internal transform (or appends these changes to an existing internal transform) to convert from frame coordinates to bounds coordinates in your view. As long as the width-to-height ratio of the two coordinate systems remains the same, your content appears normal. If the ratios differ, your content may appear skewed.

Availability

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

See Also

• – translateOriginToPoint:
• – bounds
• – setBoundsRotation:
• – setBounds:
• – setBoundsSize:
• – setPostsBoundsChangedNotifications:

Related Sample Code

• Polygons

Declared In

setBoundsRotation:

Sets the rotation of the receiver’s bounds rectangle to a specific degree value.

- (void)setBoundsRotation:(CGFloat)angle

Parameters

angle

A float value specifying the angle of rotation, in degrees.

Discussion

Positive values indicate counterclockwise rotation, negative clockwise. Rotation is performed around the coordinate system origin, (0.0, 0.0), which need not coincide with that of the frame rectangle or the bounds rectangle. This method neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

This method posts an NSViewBoundsDidChangeNotification to the default notification center if the receiver is configured to do so.

Bounds rotation affects the orientation of the drawing within the view object’s frame rectangle, but not the orientation of the frame rectangle itself. Also, for a rotated bounds rectangle to enclose all the visible areas of its view object—that is, to guarantee coverage over the frame rectangle—it must also contain some areas that aren’t visible. This can cause unnecessary drawing to be requested, which may affect performance. It may be better in many cases to rotate the coordinate system in the drawRect: method rather than use this method.

After calling this method, NSView creates an internal transform (or appends these changes to an existing internal transform) to convert from frame coordinates to bounds coordinates in your view. As long as the width-to-height ratio of the two coordinate systems remains the same, your content appears normal. If the ratios differ, your content may appear skewed.

Availability

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

See Also

• – rotateByAngle:
• – boundsRotation
• – setFrameRotation:
• – setPostsBoundsChangedNotifications:

Declared In

setBoundsSize:

Sets the size of the receiver’s bounds rectangle to specified dimensions, inversely scaling its coordinate system relative to its frame rectangle.

- (void)setBoundsSize:(NSSize)newSize

Parameters

newSize

An NSSize structure specifying the new width and height of the receiver's bounds rectangle.

Discussion

For example, a view object with a frame size of (100.0, 100.0) and a bounds size of (200.0, 100.0) draws half as wide along the x axis. This method neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

This method posts an NSViewBoundsDidChangeNotification to the default notification center if the receiver is configured to do so.

After calling this method, NSView creates an internal transform (or appends these changes to an existing internal transform) to convert from frame coordinates to bounds coordinates in your view. As long as the width-to-height ratio of the two coordinate systems remains the same, your content appears normal. If the ratios differ, your content may appear skewed.

Availability

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

See Also

• – bounds
• – setBoundsRotation:
• – setBounds:
• – setBoundsOrigin:
• – setPostsBoundsChangedNotifications:

Related Sample Code

• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

setCompositingFilter:

Sets a CoreImage filter that is used to composite the receiver’s contents with the background.

- (void)setCompositingFilter:(CIFilter *)filter

Parameters

filter

A CoreImage filter.

Discussion

This method sets the value of the compositingFilter property of the receiver’s layer.

Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

setContentFilters:

Sets the array of CoreImage filters that are applied to the contents of the receiver and its sublayers.

- (void)setContentFilters:(NSArray *)filters

Parameters

filters

An array of CoreImage filters.

Discussion

This method sets the value of the filters property of the receiver’s layer.

Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

setFocusRingType:

Sets the type of focus ring to be drawn around the receiver.

- (void)setFocusRingType:(NSFocusRingType)focusRingType

Parameters

focusRingType

An enum constant identifying a type of focus ring. Possible values are listed in NSFocusRingType. You can specify NSFocusRingTypeNone to indicate you do not want your view to have a focus ring.

Discussion

This method only sets the desired focus ring type and does not cause the view to draw the actual focus ring. You are responsible for drawing the focus ring in your view’s drawRect: method whenever your view is made the first responder.

Availability

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

See Also

• – focusRingType

Declared In

setFrame:

Sets the receiver’s frame rectangle to the specified rectangle.

- (void)setFrame:(NSRect)frameRect

Parameters

frameRect

The new frame rectangle for the view.

Discussion

This method, in setting the frame rectangle, repositions and resizes the receiver within the coordinate system of its superview. It neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

This method posts an NSViewFrameDidChangeNotification to the default notification center if the receiver is configured to do so.

If your view does not use a custom bounds rectangle, this method also sets your view bounds to match the size of the new frame. You specify a custom bounds rectangle by calling setBounds:, setBoundsOrigin:, setBoundsRotation:, or setBoundsSize:explicitly. Once set, NSView creates an internal transform to convert from frame coordinates to bounds coordinates. As long as the width-to-height ratio of the two coordinate systems remains the same, your content appears normal. If the ratios differ, your content may appear skewed.

Availability

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

See Also

• – frame
• – setFrameRotation:
• – setFrameOrigin:
• – setFrameSize:
• – setPostsFrameChangedNotifications:

Related Sample Code

• PDFKitLinker2
• Quartz Composer WWDC 2005 TextEdit
• Sketch-112
• TextEditPlus
• TipWrapper

Declared In

setFrameCenterRotation:

Rotates the frame of the receiver about the layer’s position.

- (void)setFrameCenterRotation:(CGFloat)angle

Parameters

angle

The angle to rotate the frame around the center of the receiver.

Discussion

If the application has altered the layer’s anchorPoint property, the behavior is undefined. Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

setFrameOrigin:

Sets the origin of the receiver’s frame rectangle to the specified point, effectively repositioning it within its superview.

- (void)setFrameOrigin:(NSPoint)newOrigin

Parameters

newOrigin

The point that is the new origin of the receiver's frame.

Discussion

This method neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

This method posts an NSViewFrameDidChangeNotification to the default notification center if the receiver is configured to do so.

Availability

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

See Also

• – frame
• – setFrameSize:
• – setFrame:
• – setFrameRotation:
• – setPostsFrameChangedNotifications:

Related Sample Code

• CoreRecipes
• iSpend
• Quartz Composer QCTV
• Reducer
• WhackedTV

Declared In

setFrameRotation:

Sets the rotation of the receiver’s frame rectangle to a specified degree value, rotating it within its superview without affecting its coordinate system.

- (void)setFrameRotation:(CGFloat)angle

Parameters

angle

A float value indicating the degree of rotation.

Discussion

Positive values indicate counterclockwise rotation, negative clockwise. Rotation is performed around the origin of the frame rectangle.

This method neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

This method posts an NSViewFrameDidChangeNotification to the default notification center if the receiver is configured to do so.

Availability

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

See Also

• – frameRotation
• – setBoundsRotation:

Declared In

setFrameSize:

Sets the size of the receiver’s frame rectangle to the specified dimensions, resizing it within its superview without affecting its coordinate system.

- (void)setFrameSize:(NSSize)newSize

Parameters

newSize

An NSSize structure specifying the new height and width of the frame rectangle.

Discussion

This method neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

This method posts an NSViewFrameDidChangeNotification to the default notification center if the receiver is configured to do so.

In Mac OS X version 10.4 and later, you can override this method to support content preservation during live resizing. In your overridden implementation, include some conditional code to be executed only during a live resize operation. Your code must invalidate any portions of your view that need to be redrawn.

Availability

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

See Also

• – frame
• – setFrameOrigin:
• – setFrame:
• – setFrameRotation:
• – setPostsFrameChangedNotifications:

Related Sample Code

• CoreRecipes
• MyPhoto
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus
• WhackedTV

Declared In

setHidden:

Sets whether the receiver is hidden.

- (void)setHidden:(BOOL)flag

Parameters

flag

YES if the receiver is to be hidden, NO otherwise.

Discussion

A hidden view disappears from its window and does not receive input events. It remains in its superview’s list of subviews, however, and participates in autoresizing as usual. The Application Kit also disables any cursor rectangle, tool-tip rectangle, or tracking rectangle associated with a hidden view. Hiding a view with subviews has the effect of hiding those subviews and any view descendants they might have. This effect is implicit and does not alter the hidden state of the receiver’s descendants as reported by isHidden.

Hiding the view that is the window’s current first responder causes the view’s next valid key view (nextValidKeyView) to become the new first responder. A hidden view remains in the nextKeyView chain of views it was previously part of, but is ignored during keyboard navigation.

Availability

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

See Also

• – isHidden
• – isHiddenOrHasHiddenAncestor

Related Sample Code

• CarbonCocoaCoreImageTab
• iSpend
• Reducer
• StickiesExample

Declared In

setKeyboardFocusRingNeedsDisplayInRect:

Invalidates the area around the focus ring.

- (void)setKeyboardFocusRingNeedsDisplayInRect:(NSRect)rect

Parameters

rect

The rectangle of the control or cell defining the area around the focus ring. rect will be expanded to include the focus ring for invalidation.

Availability

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

Declared In

setLayer:

Sets the Core Animation layer that the receiver uses for layer-backing to the specified layer.

- (void)setLayer:(CALayer *)newLayer

Parameters

newLayer

A Core Animation layer to use as the receiver’s backing store.

Availability

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

Declared In

setNeedsDisplay:

Controls whether the receiver's entire bounds is marked as needing display.

- (void)setNeedsDisplay:(BOOL)flag

Parameters

flag

If YES, marks the receiver’s entire bounds as needing display; if NO, marks it as not needing display.

Discussion

Whenever the data or state used for drawing a view object changes, the view should be sent a setNeedsDisplay: message. NSView objects marked as needing display are automatically redisplayed on each pass through the application’s event loop. (View objects that need to redisplay before the event loop comes around can of course immediately be sent the appropriate display... method.)

Availability

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

See Also

• – setNeedsDisplayInRect:
• – needsDisplay

Related Sample Code

• Aperture Edit Plugin - Borders & Titles
• Squiggles
• WhackedTV

Declared In

setNeedsDisplayInRect:

Marks the region of the receiver within the specified rectangle as needing display, increasing the receiver’s existing invalid region to include it.

- (void)setNeedsDisplayInRect:(NSRect)invalidRect

Parameters

invalidRect

The rectangular region of the receiver to mark as invalid; it should be specified in the coordinate system of the receiver.

Discussion

A later displayIfNeeded... method will then perform drawing only within the invalid region. View objects marked as needing display are automatically redisplayed on each pass through the application’s event loop. (View objects that need to redisplay before the event loop comes around can of course immediately be sent the appropriate display... method.)

Availability

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

See Also

• – setNeedsDisplay:
• – needsDisplay

Related Sample Code

• Reducer
• Sketch-112
• WhackedTV

Declared In

setNextKeyView:

Inserts a specified view object after the receiver in the key view loop of the receiver’s window.

- (void)setNextKeyView:(NSView *)aView

Parameters

aView

The NSView object to insert.

Availability

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

See Also

• – nextKeyView
• – nextValidKeyView
• – previousKeyView
• – previousValidKeyView

Declared In

setPostsBoundsChangedNotifications:

Controls whether the receiver informs observers when its bounds rectangle changes.

- (void)setPostsBoundsChangedNotifications:(BOOL)flag

Parameters

flag

If YES, the receiver will post notifications to the default notification center whenever its bounds rectangle changes; if flag is NO it won’t.

Discussion

Note that if flag is YES and bounds notifications are suppressed, when the bounds change notification is reenabled the view will immediately post a single such notification if its bounds changed during this time. This will happen even if there has been no net change in the view's bounds.

The following methods can result in notification posting:

• setBounds:

• setBoundsOrigin:

• setBoundsRotation:

• setBoundsSize:

• translateOriginToPoint:

• scaleUnitSquareToSize:

• rotateByAngle:

Availability

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

See Also

• – postsBoundsChangedNotifications

Declared In

setPostsFrameChangedNotifications:

Controls whether the receiver informs observers when its frame rectangle changes.

- (void)setPostsFrameChangedNotifications:(BOOL)flag

Parameters

flag

If YES, the receiver will post notifications to the default notification center whenever its frame rectangle changes; if flag is NO it won’t.

Discussion

Note that if flag is YES and frame notifications are suppressed, when the frame change notification is reenabled the view will immediately post a single such notification if its frame changed during this time. This will happen even if there has been no net change in the view's frame.

The following methods can result in notification posting:

• setFrame:

• setFrameOrigin:

• setFrameRotation:

• setFrameSize:

Availability

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

See Also

• – postsFrameChangedNotifications

Declared In

setShadow:

Sets the shadow drawn by the receiver.

- (void)setShadow:(NSShadow *)shadow

Parameters

shadow

An instance of NSShadow.

Discussion

This method sets the shadowColor,shadowOffset, shadowOpacity and shadowRadius properties of the receiver’s layer.

Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

setSubviews:

Sets the receiver’s subviews to the specified subviews.

- (void)setSubviews:(NSArray *)newSubviews

Parameters

newSubviews

An array of subviews. The newSubviews array can consist of existing subviews of the receiver or other views that have nil as their superview.  If newSubviews is nil, or contains duplicated views, or if any of its members have a superview other than nil or the reciever, an invalid argument exception is thrown.

Discussion

Using this method you can: reorder the receiver’s existing subviews, add or remove subviews en masse, replace all of the receiver’s subviews with a new set of subviews, or remove all the receiver’s subviews.

Given a valid array of views in newSubviews, setSubviews: performs any required sorting of the subviews array, as well as sending any addSubview: and removeFromSuperview messages as necessary to leave the receiver with the requested new array of subviews.  Any member of newSubviews that isn't already a subview of the receiver is added.  Any member of the view's existing subviews array that isn't in newSubviews is removed.  And any views that are in both subviews and newSubviews are moved in the subviews array as needed, without being removed and re-added.

This method marks the affected view and window areas as needing display.

Availability

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

Declared In

setToolTip:

Sets the tool tip text for the view to string.

- (void)setToolTip:(NSString *)string

Parameters

string

A string that contains the text to use for the tool tip. If nil, it cancels tool tip display for the view.

Availability

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

See Also

• – toolTip

Declared In

setUpGState

Overridden by subclasses to (re)initialize the receiver’s graphics state object.

- (void)setUpGState

Discussion

This method is automatically invoked when the graphics state object created using allocateGState needs to be initialized. The default implementation does nothing. Your subclass can override it to set the current font, line width, or any other graphics state parameter except coordinate transformations and the clipping path—these are established by the frame and bounds rectangles and by methods such as scaleUnitSquareToSize: and translateOriginToPoint:. Note that drawRect: can further transform the coordinate system and clipping path for whatever temporary effects it needs.

Availability

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

See Also

• – allocateGState
• – renewGState

Declared In

setWantsLayer:

Specifes whether the receiver and its subviews use a Core Animation layer as a backing store.

- (void)setWantsLayer:(BOOL)flag

Parameters

flag

YES if the receiver and its subviews should use a Core Animation layer as its backing store, otherwise NO.

Availability

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

Declared In

shadow

Returns the shadow drawn by the receiver

- (NSShadow *)shadow

Return Value

An instance of NSShadow that is created using the shadowColor,shadowOffset, shadowOpacity and shadowRadius properties of the receiver’s layer.

Discussion

Sending this message to a view that is not managing a Core Animation layer causes an exception.

Availability

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

Declared In

shouldDelayWindowOrderingForEvent:

Overridden by subclasses to allow the user to drag images from the receiver without its window moving forward and possibly obscuring the destination and without activating the application.

- (BOOL)shouldDelayWindowOrderingForEvent:(NSEvent *)theEvent

Parameters

theEvent

An object representing an initial mouse-down event.

Return Value

If this method returns YES, the normal window-ordering and activation mechanism is delayed (not necessarily prevented) until the next mouse-up event. If it returns NO, then normal ordering and activation occur.

Discussion

Never invoke this method directly; it’s invoked automatically for each mouse-down event directed at the NSView.

An NSView subclass that allows dragging should implement this method to return YES if theEvent is potentially the beginning of a dragging session or of some other context where window ordering isn’t appropriate. This method is invoked before a mouseDown: message for theEvent is sent. The default implementation returns NO.

If, after delaying window ordering, the receiver actually initiates a dragging session or similar operation, it should also send a preventWindowOrdering message to NSApp, which completely prevents the window from ordering forward and the activation from becoming active. preventWindowOrdering is sent automatically by the NSView dragImage:... and dragFile:... methods.

Availability

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

Declared In

shouldDrawColor

Returns NO if the receiver is being drawn in an NSWindow object (as opposed, for example, to being printed) and the window object can’t store color; otherwise returns YES.

- (BOOL)shouldDrawColor

Discussion

A view object can base its drawing behavior on the return value of this method to improve its appearance in grayscale windows.

Availability

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

See Also

• – drawRect:
• – canStoreColor (NSWindow)

Declared In

sortSubviewsUsingFunction:context:

Orders the receiver's immediate subviews using the specified comparator function.

- (void)sortSubviewsUsingFunction:(NSComparisonResult (*)(id, id, void *))compare context:(void *)context

Parameters

compare

A pointer to the comparator function. This function must take as arguments two subviews to be ordered and contextual data (supplied in context which may be arbitrary data used to help in the comparison. The comparator function should return NSOrderedAscending if the first subview should be ordered lower, NSOrderedDescending if the second subview should be ordered lower, and NSOrderedSame if their ordering isn’t important.

context

Arbitrary data that might help the comparator function compare in its decisions.

Availability

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

See Also

• sortedArrayUsingFunction:context: (NSArray)

Declared In

subviews

Return the receiver’s immediate subviews.

- (NSArray *)subviews

Return Value

Returns an array containing the receiver’s subviews.

Discussion

The order of the subviews may be considered as being back-to-front, but this does not imply invalidation and drawing behavior. The order is based on the order of the receiver's subviews as specified in the nib file from which they were unarchived or the programmatic interface for modifying the receiver's subview list. This ordering is also the reverse of the order in which hit-testing is done.

Availability

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

See Also

• – superview
• – addSubview:
• – addSubview:positioned:relativeTo:
• – removeFromSuperview

Related Sample Code

• CarbonCocoaCoreImageTab
• CoreRecipes
• MyPhoto
• Reducer
• WhackedTV

Declared In

superview

Returns the receiver’s superview, or nil if it has none.

- (NSView *)superview

Discussion

When applying this method iteratively or recursively, be sure to compare the returned view object to the content view of the window to avoid proceeding out of the view hierarchy.

Availability

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

See Also

• – window
• – subviews
• – removeFromSuperview

Related Sample Code

• Quartz Composer WWDC 2005 TextEdit
• Reducer
• TextEditPlus
• WebKitDOMElementPlugIn

Declared In

tag

Returns the receiver’s tag, an integer that you can use to identify view objects in your application.

- (NSInteger)tag

Discussion

The default implementation returns –1. Subclasses can override this method to provide individual tags, possibly adding storage and a setTag: method (which NSView doesn’t define).

Availability

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

See Also

• – viewWithTag:

Related Sample Code

• CIVideoDemoGL
• GLChildWindowDemo
• Quartz2DBasics

Declared In

toolTip

Returns the text for the view’s tool tip.

- (NSString *)toolTip

Return Value

The tool tip text or nil if the view doesn’t currently display tool tip text

Availability

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

See Also

• – setToolTip:

Declared In

trackingAreas

Returns an array of the receiver’s tracking areas.

- (NSArray *)trackingAreas

Return Value

An array of the receiver’s tracking areas (instances of NSTrackingArea). If the receiver has no tracking areas, returns an empty array.

Availability

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

Related Sample Code

• MenuItemView

Declared In

translateOriginToPoint:

Translates the receiver’s coordinate system so that its origin moves to a new location.

- (void)translateOriginToPoint:(NSPoint)newOrigin

Parameters

newOrigin

A point that specifies the new origin.

Discussion

In the process, the origin of the receiver’s bounds rectangle is shifted by (–newOrigin.x, –newOrigin.y). This method neither redisplays the receiver nor marks it as needing display. You must do this yourself with display or setNeedsDisplay:.

Note the difference between this method and setting the bounds origin. Translation effectively moves the image inside the bounds rectangle, while setting the bounds origin effectively moves the rectangle over the image. The two are in a sense inverse, although translation is cumulative, and setting the bounds origin is absolute.

This method posts an NSViewBoundsDidChangeNotification to the default notification center if the receiver is configured to do so.

Availability

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

See Also

• – setBoundsOrigin:
• – setBounds:
• – setPostsBoundsChangedNotifications:

Related Sample Code

• Polygons

Declared In

translateRectsNeedingDisplayInRect:by:

Translates the display rectangles by the specified delta.

- (void)translateRectsNeedingDisplayInRect:(NSRect)clipRectby:(NSSize)delta

Parameters

clipRect

A rectangle defining the region of the receiver, typically the receiver’s bounds.

delta

A NSSize structure that specifies an offset from from aRect’s origin.

Discussion

The method is similar to the scrollRect:by: method:

1. It collects the receiving view's dirty rectangles.

2. Clears all dirty rectangles in the intersection of clipRect and the view's bounds.

3. Shifts the retrieved rectangles by the delta offset.

4. Clips the result to the intersection of clipRect and the view's bounds

5. Draws the resultant rectangles in the view.

The developer must ensure that clipRect and delta are pixel-aligned in order to guarantee correct drawing. See View Coordinate Conversion in View Programming Guide for Cocoa for a description of how to pixel-align view coordinates.

Availability

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

Declared In

unlockFocus

Balances an earlier lockFocus or lockFocusIfCanDraw message; restoring the focus to the previously focused view is necessary.

- (void)unlockFocus

Discussion

Raises an NSInvalidArgumentException if invoked on the wrong view.

Availability

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

See Also

• – allocateGState

Related Sample Code

• MungSaver
• QTKitFrameStepper

Declared In

unregisterDraggedTypes

Unregisters the receiver as a possible destination in a dragging session.

- (void)unregisterDraggedTypes

Availability

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

See Also

• – registerForDraggedTypes:

Declared In

updateTrackingAreas

Invoked automatically when the view’s geometry changes such that its tracking areas need to be recalculated.

- (void)updateTrackingAreas

Discussion

You should override this method to remove out of date tracking areas and add recomputed tracking areas; your implementation should call super.

Availability

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

Declared In

viewDidEndLiveResize

Informs the receiver of the end of a live resize.

- (void)viewDidEndLiveResize

Discussion

In the simple case, a view is sent viewWillStartLiveResize before the first resize operation on the containing window and viewDidEndLiveResize after the last resize operation. A view that is repeatedly added and removed from a window during live resize will receive only one viewWillStartLiveResize (on the first time it is added to the window) and one viewDidEndLiveResize (when the window has completed the live resize operation). This allows a superview such as NSBrowser object to add and remove its NSMatrix subviews during live resize without the NSMatrix receiving multiple calls to these methods.

A view might allocate data structures to cache-drawing information in viewWillStartLiveResize and should clean up these data structures in viewDidEndLiveResize. In addition, a view that does optimized drawing during live resize might want to do full drawing after viewDidEndLiveResize, although a view should not assume that it has a drawing context in viewDidEndLiveResize (since it may have been removed from the window during live resize). A view that wants to redraw itself after live resize should call [self setNeedsDisplay:YES] in viewDidEndLiveResize.

A view subclass should call super from these methods.

Availability

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

See Also

• – viewWillStartLiveResize
• – inLiveResize

Related Sample Code

• MyPhoto

Declared In

viewDidHide

Invoked when the receiver is hidden, either directly, or in response to an ancestor being hidden.

- (void)viewDidHide

Discussion

The receiver receives this message when its isHiddenOrHasHiddenAncestor state goes from NO to YES.  This will happen when the view or an ancestor is marked as hidden, or when the view or an ancestor is inserted into a new view hierarchy.

Availability

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

Declared In

viewDidMoveToSuperview

Informs the receiver that its superview has changed (possibly to nil).

- (void)viewDidMoveToSuperview

Discussion

The default implementation does nothing; subclasses can override this method to perform whatever actions are necessary.

Availability

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

See Also

• – viewDidMoveToWindow
• – viewWillMoveToSuperview:
• – viewWillMoveToWindow:

Declared In

viewDidMoveToWindow

Informs the receiver that it has been added to a new view hierarchy.

- (void)viewDidMoveToWindow

Discussion

The default implementation does nothing; subclasses can override this method to perform whatever actions are necessary.

window may return nil when this method is invoked, indicating that the receiver does not currently reside in any window. This occurs when the receiver has just been removed from its superview or when the receiver has just been added to a superview that does not itself have a window. Overrides of this method may choose to ignore such cases if they are not of interest.

Availability

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

See Also

• – viewDidMoveToSuperview
• – viewWillMoveToSuperview:
• – viewWillMoveToWindow:

Related Sample Code

• Clock Control
• Dicey
• GLChildWindowDemo
• SpotlightAPI
• WhackedTV

Declared In

viewDidUnhide

Invoked when the receiver is unhidden, either directly, or in response to an ancestor being unhidden

- (void)viewDidUnhide

Discussion

The receiver receives this message when its isHiddenOrHasHiddenAncestor state goes from YES to NO.  This can happen when the view or an ancestor is marked as not hidden, or when the view or an ancestor is removed from its containing view hierarchy.

Availability

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

Declared In

viewWillDraw

Informs the receiver that it will be required to draw content.

- (void)viewWillDraw

Discussion

In response to receiving one of the display... messages the receiver will recurse down the view hierarchy, sending this message to each of the views that may be involved in the display operation.

Subclasses can override this method to move or resize views, mark additional areas as requiring display, or other actions that can best be deferred until they are required for drawing. During the recursion, sending of setNeedsDisplay: and setNeedsDisplayInRect: messages to views in the hierarchy that's about to be drawn is valid and supported, and will affect the assessment of the total area to be rendered in that drawing pass.

A subclass’s implementation of viewWillDraw can use the existing NSView getRectsBeingDrawn:count: method to obtain a list of rectangles that bound the affected area, enabling it to restrict its efforts to that area.

The following is an example of a generic subclass implementation:

- (void)viewWillDraw {

    // Perform some operations before recursing for descendants.

    // Now recurse to handle all our descendants.

    // Overrides must call up to super like this.

    [super viewWillDraw];

    // Perform some operations that might depend on descendants

    //  already having had a chance to update.

} 

Availability

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

Declared In

viewWillMoveToSuperview:

Informs the receiver that its superview is about to change to the specified superview (which may be nil).

- (void)viewWillMoveToSuperview:(NSView *)newSuperview

Parameters

newSuperview

A view object that will be the new superview of the receiver.

Discussion

Subclasses can override this method to perform whatever actions are necessary.

Availability

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

See Also

• – viewDidMoveToSuperview
• – viewDidMoveToWindow
• – viewWillMoveToWindow:

Declared In

viewWillMoveToWindow:

Informs the receiver that it’s being added to the view hierarchy of the specified window object (which may be nil).

- (void)viewWillMoveToWindow:(NSWindow *)newWindow

Parameters

newWindow

A window object that will be at the root of the receiver's new view hierarchy.

Discussion

Subclasses can override this method to perform whatever actions are necessary.

Availability

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

See Also

• – viewDidMoveToSuperview
• – viewDidMoveToWindow
• – viewWillMoveToSuperview:

Declared In

viewWillStartLiveResize

Informs the receiver of the start of a live resize.

- (void)viewWillStartLiveResize

Discussion

In the simple case, a view is sent viewWillStartLiveResize before the first resize operation on the containing window and viewDidEndLiveResize after the last resize operation. A view that is repeatedly added and removed from a window during live resize will receive only one viewWillStartLiveResize (on the first time it is added to the window) and one viewDidEndLiveResize (when the window has completed the live resize operation). This allows a superview such as NSBrowser object to add and remove its NSMatrix subviews during live resize without the NSMatrix object receiving multiple calls to these methods.

A view might allocate data structures to cache-drawing information in viewWillStartLiveResize and should clean up these data structures in viewDidEndLiveResize. In addition, a view that does optimized drawing during live resize might want to do full drawing after viewDidEndLiveResize, although a view should not assume that it has a drawing context in viewDidEndLiveResize (since it may have been removed from the window during live resize). A view that wants to redraw itself after live resize should call [self setNeedsDisplay:YES] in viewDidEndLiveResize.

A view subclass should call super from these methods.

Availability

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

See Also