Mac Developer Library

Developer

AppKit Framework Reference NSView Class Reference

Options
Deployment Target:

On This Page
Language:

NSView

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

Class at a Glance

The NSView class defines the basic drawing, event-handling, and printing architecture of an app. You typically do not use NSView objects directly. Instead, you use objects whose classes descend from NSView or you subclass NSView yourself and override its methods to implement the behavior you need. For any view object, there are many methods that you can use as-is.

The NSView class provides the infrastructure for drawing, printing, and handling events in your app. Instances of the NSView class (or one of its subclasses) are commonly known as view objects, or simply as views.

Views handle the presentation and interaction with your app’s visible content. You arrange one or more views inside an NSWindow object, which acts as a wrapper for your content. A view object defines a rectangular region for drawing and receiving mouse events. Views handle other chores as well, including the dragging of icons and working with the NSScrollView class to support efficient scrolling.

Most of the functionality of the NSView class is automatically invoked by the Application Kit. 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 Cocoa Event Handling Guide. For more information on displaying tooltips and contextual menus, see Displaying Contextual Menus and Managing 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 Mouse Events" and "Mouse Events").

Handling Events in Your Subclass

If you subclass NSView directly and handle specific types of events, the implementation of your event-related methods should generally not call super. Views inherit their event-handling capabilities from their NSResponder parent class. The default behavior for responders is to pass events up the responder chain, which is not the behavior you typically want if you handle events in a custom view. Therefore, you should not call super if your view implements any of the following methods and handles the event:

If your view descends from a class other than NSView, call super to let the parent view handle any events that you do not.

  • init(frame:) - initWithFrame: Designated Initializer

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

    Declaration

    Swift

    init(frame frameRect: NSRect)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Restores the view to an initial state so that it can be reused.

    Declaration

    Swift

    func prepareForReuse()

    Objective-C

    - (void)prepareForReuse

    Discussion

    The default implementation of this method sets the window’s alpha to 1.0 and its hidden state to NOfalse. Subclasses can override this method and use it to return the view to its initial state. Subclasses should call super at some point in their implementation.

    This method offers a way to reset a view to some initial state so that it can be reused. For example, the NSTableView class uses it to prepare views for reuse and thereby avoid the expense of creating new views as they scroll into view. If you implement a view-reuse system in your own code, you can call this method from your own code prior to reusing them.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • superview superview Property

    The view that is the parent of the current view. (read-only)

    Declaration

    Swift

    unowned(unsafe) var superview: NSView? { get }

    Objective-C

    @property(readonly, assign) NSView *superview

    Discussion

    The superview is the immediate ancestor of the current view. The value of this property is nil when the view is not installed in a view hierarchy. To set the value of this property, use the addSubview: method to embed the current view inside another view.

    When checking the value of this property iteratively or recursively, be sure to compare the superview object to the content view of the window to avoid proceeding out of the view hierarchy.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s subviews to the specified subviews.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.5 and later.

  • subviews subviews Property

    The array of views embedded in the current view.

    Declaration

    Swift

    var subviews: [AnyObject]

    Objective-C

    @property(copy) NSArray *subviews

    Discussion

    This array contains zero or more NSView objects that represent the views embedded in the current view’s content. The current view acts as the superview for each subview. The order of the subviews may be considered as being back-to-front, but this does not imply invalidation and drawing behavior.

    When loading a view from a nib or storyboard file, the order of subviews is determined by the nib or storyboard file itself and usually corresponds to the order in which the views were added. Similarly, when adding subviews programmatically, the order is based on the order in which you added them.

    When performing hit-test operations on a view, you should start at the last view in this array and work backwards.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • window window Property

    The receiver’s window object, if it is installed in a window. (read-only)

    Declaration

    Swift

    unowned(unsafe) var window: NSWindow? { get }

    Objective-C

    @property(readonly, assign) NSWindow *window

    Discussion

    The value of this property is nil if the view is not currently installed in a window.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    superview

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

    Declaration

    Swift

    func addSubview(_ aView: NSView)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func addSubview(_ aView: NSView, positioned place: NSWindowOrderingMode, relativeTo otherView: NSView?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func didAddSubview(_ subview: NSView)

    Objective-C

    - (void)didAddSubview:(NSView *)subview

    Parameters

    subview

    The view that was added as a subview.

    Discussion

    This method is invoked by addSubview:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeFromSuperview()

    Objective-C

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

    Calling this method removes any constraints that refer to the view you are removing, or that refer to any view in the subtree of the view you are removing.

    Never invoke this method during display.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeFromSuperviewWithoutNeedingDisplay()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func replaceSubview(_ oldView: NSView, with newView: NSView)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func isDescendantOf(_ aView: NSView) -> Bool

    Objective-C

    - (BOOL)isDescendantOf:(NSView *)aView

    Parameters

    aView

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

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The view’s closest opaque ancestor, which might be the view itself. (read-only)

    Declaration

    Swift

    unowned(unsafe) var opaqueAncestor: NSView? { get }

    Objective-C

    @property(readonly, assign) NSView *opaqueAncestor

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func ancestorSharedWithView(_ aView: NSView) -> NSView?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func sortSubviewsUsingFunction(_ compare: CFunctionPointer<((AnyObject!, AnyObject!, UnsafeMutablePointer<Void>) -> NSComparisonResult)>, context context: UnsafeMutablePointer<Void>)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Informs the receiver that its superview has changed (possibly to nil).

    Declaration

    Swift

    func viewDidMoveToSuperview()

    Objective-C

    - (void)viewDidMoveToSuperview

    Discussion

    The default implementation does nothing; subclasses can override this method to perform whatever actions are necessary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Informs the receiver that it has been added to a new view hierarchy.

    Declaration

    Swift

    func viewDidMoveToWindow()

    Objective-C

    - (void)viewDidMoveToWindow

    Discussion

    The default implementation does nothing; subclasses can override this method to perform whatever actions are necessary.

    If the view’s window property is nil, that result signifies that the view was removed from its window and does not currently reside in any window.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Informs the receiver that its superview is about to change to the specified superview (which may be nil).

    Declaration

    Swift

    func viewWillMoveToSuperview(_ newSuperview: NSView?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Informs the receiver that it’s being added to the view hierarchy of the specified window object (which may be nil).

    Declaration

    Swift

    func viewWillMoveToWindow(_ newWindow: NSWindow?)

    Objective-C

    - (void)viewWillMoveToWindow:(NSWindow *)newWindow

    Parameters

    newWindow

    The window object that will be at the root of the receiver's new view hierarchy. If the view is being removed from a window and there is no new window, this parameter is nil.

    Discussion

    AppKit calls this method when the window of a view changes. It also calls it in cases where a view stays in the same window but its position in its view hierarchy changes. The view that moved also calls this method on all of its subviews, giving each of them a chance to respond to the change.

    Subclasses can override this method to perform whatever actions are necessary. For example, when a window is deallocated, you can use this method to remove notification observers and bindings associated with the view.

    When a window is deallocated, AppKit calls this method for each view in the window, passing nil for the newWindow parameter. AppKit does not necessarily call this method when closing a window, though. Closing a window usually just hides the window. Closed windows are deallocated only if their isReleasedWhenClosed method returns YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Overridden by subclasses to perform additional actions before subviews are removed from the receiver.

    Declaration

    Swift

    func willRemoveSubview(_ subview: NSView)

    Objective-C

    - (void)willRemoveSubview:(NSView *)subview

    Parameters

    subview

    The subview that will be removed.

    Discussion

    This method is invoked when subview receives a removeFromSuperview message or subview is removed from the receiver due to it being added to another view with addSubview:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The menu item containing the view or any of its superviews in the view hierarchy. (read-only)

    Declaration

    Swift

    var enclosingMenuItem: NSMenuItem? { get }

    Objective-C

    @property(readonly, strong) NSMenuItem *enclosingMenuItem

    Discussion

    The value of this property is nil if the view is not in a menu item.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • frame frame Property

    The receiver’s frame rectangle, which defines its position and size in its superview’s coordinate system.

    Declaration

    Swift

    var frame: NSRect

    Objective-C

    @property NSRect frame

    Discussion

    Changing the value of this property repositions and resizes the receiver within the coordinate system of its superview. Changing the frame does not mark the view as needing to be displayed. Call the setNeedsDisplay: method when you want the view to be redisplayed.

    If your view does not use a custom bounds rectangle, this method also sets the view’s bounds to match the size of the new frame. You can specify a custom bounds rectangle by changing the bounds property or by calling the setBoundsOrigin:, setBoundsRotation:, or setBoundsSize: method explicitly. Once set, the view 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.

    The frame rectangle may be rotated relative to its superview’s coordinate system. For more information, see the frameRotation property.

    Changing the value of this property results in the posting of an NSViewFrameDidChangeNotification to the default notification center if the view is configured to do so. You can configure this behavior by calling the setPostsFrameChangedNotifications: method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    bounds

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

    Declaration

    Swift

    func setFrameOrigin(_ newOrigin: NSPoint)

    Objective-C

    - (void)setFrameOrigin:(NSPoint)newOrigin

    Parameters

    newOrigin

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

    Discussion

    Changing the frame does not mark the view as needing to be displayed. Call the setNeedsDisplay: method when you want the view to be redisplayed.

    Changing the frame origin results in the posting of an NSViewFrameDidChangeNotification to the default notification center if the view is configured to do so. You can configure this behavior by calling the setPostsFrameChangedNotifications: method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func setFrameSize(_ newSize: NSSize)

    Objective-C

    - (void)setFrameSize:(NSSize)newSize

    Parameters

    newSize

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

    Discussion

    Changing the frame does not mark the view as needing to be displayed. Call the setNeedsDisplay: method when you want the view to be redisplayed.

    Changing the frame size results in the posting of an NSViewFrameDidChangeNotification to the default notification center if the view is configured to do so. You can configure this behavior by calling the setPostsFrameChangedNotifications: method.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The angle of rotation, measured in degrees, applied to the view’s frame rectangle relative to its superview’s coordinate system.

    Declaration

    Swift

    var frameRotation: CGFloat

    Objective-C

    @property CGFloat frameRotation

    Discussion

    Positive values indicate counterclockwise rotation. Negative values indicate clockwise rotation. Rotation is performed around the origin of the frame rectangle. Changing the value of this property does not mark the view as needing to be displayed. Call the setNeedsDisplay: method when you want the view to be redisplayed.

    Changing the frame rotation value results in the posting of an NSViewFrameDidChangeNotification to the default notification center if the view is configured to do so. You can configure this behavior by calling the setPostsFrameChangedNotifications: method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    boundsRotation

  • bounds bounds Property

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

    Declaration

    Swift

    var bounds: NSRect

    Objective-C

    @property NSRect bounds

    Discussion

    By default, this property contains a rectangle whose origin is (0, 0) and whose size matches the size of the receiver’s frame rectangle (measured in points). In 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 property saves 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 getting the value of the boundsRotation property.

    Changing the bounds does not mark the view as needing to be displayed. Call the setNeedsDisplay: method when you want the view to be redisplayed. After changing the bounds rectangle, the view 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.

    Changing the value of this property results in the posting of an NSViewBoundsDidChangeNotification to the default notification center if the view is configured to do so. You can configure this behavior by calling the setPostsBoundsChangedNotifications: method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    frame

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

    Declaration

    Swift

    func setBoundsOrigin(_ newOrigin: NSPoint)

    Objective-C

    - (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. Call the setNeedsDisplay: method when you want the view to be redisplayed.

    This method posts an NSViewBoundsDidChangeNotification to the default notification center if the view is configured to do so. You can configure this behavior by calling the setPostsBoundsChangedNotifications: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func setBoundsSize(_ newSize: NSSize)

    Objective-C

    - (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. Call the setNeedsDisplay: method when you want the view to be redisplayed.

    This method posts an NSViewBoundsDidChangeNotification to the default notification center if the view is configured to do so. You can configure this behavior by calling the setPostsBoundsChangedNotifications: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The angle of rotation, measured in degrees, applied to the view’s bounds rectangle relative to its frame rectangle.

    Declaration

    Swift

    var boundsRotation: CGFloat

    Objective-C

    @property CGFloat boundsRotation

    Discussion

    Positive values indicate counterclockwise rotation. Negative values indicate clockwise rotation. 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. Changing the value of this property neither redisplays the view nor marks it as needing display. Call the setNeedsDisplay: method when you want the view to be redisplayed.

    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 changing the value of this property, the view 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.

    Changing the value of this property results in the posting of an NSViewBoundsDidChangeNotification to the default notification center if the view is configured to do so. You can configure this behavior by calling the setPostsBoundsChangedNotifications: method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value indicating whether the view uses a layer as its backing store.

    Declaration

    Swift

    var wantsLayer: Bool

    Objective-C

    @property BOOL wantsLayer

    Discussion

    Setting the value of this property to YEStrue turns the view into a layer-backed view—that is, the view uses a CALayer object to manage its rendered content. Creating a layer-backed view implicitly causes the entire view hierarchy under that view to become layer-backed. Thus, the view and all of its subviews (including subviews of subviews) become layer-backed. The default value of this property is NOfalse.

    In a layer-backed view, any drawing done by the view is cached to the underlying layer object. This cached content can then be manipulated in ways that are more performant than redrawing the view contents explicitly. AppKit automatically creates the underlying layer object (using the makeBackingLayer method) and handles the caching of the view’s content. If the wantsUpdateLayer method returns NOfalse, you should not interact with the underlying layer object directly. Instead, use the methods of this class to make any changes to the view and its layer. If wantsUpdateLayer returns YEStrue, it is acceptable (and appropriate) to modify the layer in the view’s updateLayer method.

    For layer-backed views, you can flatten the layer hierarchy by setting the canDrawSubviewsIntoLayer property to YEStrue. To prevent a subview from having its contents flattened into this view’s layer, explicitly set the value of the subview’s wantsLayer property to YEStrue.

    In addition to creating a layer-backed view, you can create a layer-hosting view by assigning a layer directly to the view’s layer property. In a layer-hosting view, you are responsible for managing the view’s layer. To create a layer-hosting view, you must set the layer property first and then set this property to YEStrue. The order in which you set the values of these properties is crucial.

    In a layer-hosting view, do not rely on the view for drawing. Similarly, do not add subviews to a layer-hosting view. The root layer—that is, the layer you set using the layer property—becomes the root layer of the layer tree. Any manipulations of that layer tree must be done using the Core Animation interfaces. You still use the view for handling mouse and keyboard events, but drawing must be handled by Core Animation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • A Boolean value indicating which drawing path the view takes when updating its contents. (read-only)

    Declaration

    Swift

    var wantsUpdateLayer: Bool { get }

    Objective-C

    @property(readonly) BOOL wantsUpdateLayer

    Discussion

    A view can update its contents using one of two techniques. It can draw those contents using its drawRect: method or it can modify its underlying layer object directly. During the view update cycle, each dirty view calls this method on itself to determine which technique to use. The default implementation of this method returns NOfalse, which causes the view to use its drawRect: method.

    If your view is layer-backed and updates itself by modifying its layer, override this property and change the return value to YEStrue. Modifying the layer is significantly faster than redrawing the layer contents using drawRect:. If you override this property to be YEStrue, you must also override the updateLayer method of your view and use it to make the changes to your layer. Do not modify your layer in your implementation of this property. Your implementation should return YEStrue or NOfalse quickly and not perform other tasks.

    If the canDrawSubviewsIntoLayer property is set to YEStrue, the view ignores the value returned by this method. Instead, the view always uses its drawRect: method to draw its content.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.8 and later.

    See Also

    – updateLayer

  • layer layer Property

    The Core Animation layer that the view uses as its backing store.

    Declaration

    Swift

    var layer: CALayer?

    Objective-C

    @property(strong) CALayer *layer

    Discussion

    Use this property to set or get the layer associated with the view, if any. When set, the layer serves as the backing store for the view’s contents.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Creates the view’s backing layer.

    Declaration

    Swift

    func makeBackingLayer() -> CALayer

    Objective-C

    - (CALayer *)makeBackingLayer

    Return Value

    The layer to use as the view’s backing layer.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • The current layer contents placement policy.

    Declaration

    Swift

    var layerContentsPlacement: NSViewLayerContentsPlacement

    Objective-C

    @property NSViewLayerContentsPlacement layerContentsPlacement

    Discussion

    The content placement determines how the backing layer’s existing cached content image will be mapped into the layer as the layer is resized. It is analogous to, and underpinned by, the contentsGravity property of the CALayer class. The default value of this property is NSViewLayerContentsPlacementScaleAxesIndependently. For a list of supported values, see NSViewLayerContentsPlacement.

    For additional information about the performance impacts of this property, see the layerContentsRedrawPolicy property.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • The contents redraw policy for the view’s layer.

    Declaration

    Swift

    var layerContentsRedrawPolicy: NSViewLayerContentsRedrawPolicy

    Objective-C

    @property NSViewLayerContentsRedrawPolicy layerContentsRedrawPolicy

    Discussion

    The layerContentsRedrawPolicy and layerContentsPlacement settings can have significant impacts on performance. If you do not need to redraw your view during each frame update cycle, or if you are willing to accept an approximation of the view’s intermediate appearance during potentially brief animations in exchange for an animation performance and smoothness benefit, you can change the value of this property to one of the modes that does not require constant redrawing. When you do so, you must also specify the desired layer content placement for the view. The content placement determines how the backing layer’s existing cached content image will be mapped into the layer as the layer is resized. It is analogous to, and underpinned by, the contentsGravity property of the CALayer class.

    For a view that has no associated layer, or that has been assigned a developer-provided layer (a layer-hosting view) using the layer property, the default contents redraw policy is NSViewLayerContentsRedrawNever and the layerContentsPlacement property is set to NSViewLayerContentsPlacementScaleAxesIndependently. These policies tell AppKit not to replace the layer’s content and to provide the same content placement as the kCAGravityResize option. For a layer-backed view—that is, a view for which AppKit created the layer—AppKit sets the contents redraw policy to NSViewLayerContentsRedrawDuringViewResize by default. This policy forces the view’s content to be continually redrawn into the view’s backing layer during animated resizing of the view, which produces correct but not optimal performance results.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • A Boolean value indicating whether the view incorporates content from its subviews into its own layer.

    Declaration

    Swift

    var canDrawSubviewsIntoLayer: Bool

    Objective-C

    @property BOOL canDrawSubviewsIntoLayer

    Discussion

    When the value of this property is YEStrue, any subviews that have an implicitly created layer—that is, layers for which you did not explicitly set the wantsLayer property to YEStrue—draw their contents into the current view’s layer. In other words, the subviews do not get a layer of their own. Instead, they draw their content into the parent view’s layer. All views involved in the operation draw their content using their drawRect: method. They do not use the updateLayer method to update their layer contents, even if the wantsUpdateLayer property is set to YEStrue.

    Use this property to flatten the layer hierarchy for a layer-backed view and its subviews. Flattening a layer hierarchy reduces the number of layers (and may reduce the amount of memory) used by your view hierarchy. Reducing the number of layers can be more efficient in situations where there is significant overlap among the subviews or where the content of the view and subviews does not change significantly. For example, flattening a hierarchy reduces the amount of time spent compositing your views together. Do not flatten a view hierarchy if you plan to animate one or more subviews in that hierarchy.

    When changing the value of this property, the current view must have a layer object. The default value of this property is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

  • A Boolean value indicating whether the view’s layer uses Core Image filters and needs in-process rendering.

    Declaration

    Swift

    var layerUsesCoreImageFilters: Bool

    Objective-C

    @property BOOL layerUsesCoreImageFilters

    Discussion

    If your view uses a custom layer and you assigned Core Image to that layer directly, you must set this property to YEStrue to let AppKit know of that fact. In OS X v10.9 and later, AppKit prefers to render layer trees out-of-process but cannot do so if any layers have Core Image filters attached to them. Specifying YEStrue for property lets AppKit know that it must move rendering of the layer hierarchy back into your app’s process. If the value of this property is NOfalse, adding a filter to the view’s layer triggers an exception.

    You do not need to modify this property if you assigned the filters using the backgroundFilters, compositingFilter, or contentFilters properties of the view. Those methods automatically let AppKit know that it needs to render the layer hierarchy in-process. Set it only if you set the filters on the layer directly.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

  • The opacity of the view.

    Declaration

    Swift

    var alphaValue: CGFloat

    Objective-C

    @property CGFloat alphaValue

    Discussion

    This property contains the opacity value from the view’s layer. The acceptable range of values for this property are between 0.0 (transparent) and 1.0 (opaque). The default value of this property is 1.0.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The rotation angle of the view around the center of its layer.

    Declaration

    Swift

    var frameCenterRotation: CGFloat

    Objective-C

    @property CGFloat frameCenterRotation

    Discussion

    This property contains the angle of rotation of the view’s frame around its center. If you changed the underlying layer’s anchorPoint property, the result of setting this property is undefined.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • An array of Core Image filters to apply to the view’s background.

    Declaration

    Swift

    var backgroundFilters: [AnyObject]

    Objective-C

    @property(copy) NSArray *backgroundFilters

    Discussion

    This property contains an array of CIFilter objects. This array represents the background filters stored in the backgroundFilters property of the view’s layer. If the view does not have a layer, setting the value of this property has no effect.

    The default value of this property is an empty array.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The Core Image filter used to composite the view’s contents with its background.

    Declaration

    Swift

    var compositingFilter: CIFilter?

    Objective-C

    @property(strong) CIFilter *compositingFilter

    Discussion

    This property contains the compositing filter stored in the compositingFilter property of the view’s layer. If the view does not have a layer, setting the value of this property has no effect.

    The default value of this property is nil, which causes content to be rendered without any special compositing effects.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • An array of Core Image filters to apply to the contents of the view and its sublayers.

    Declaration

    Swift

    var contentFilters: [AnyObject]

    Objective-C

    @property(copy) NSArray *contentFilters

    Discussion

    This property contains an array of CIFilter objects. This array represents the filters stored in the filters property of the view’s layer. If the view does not have a layer, setting the value of this property has no effect.

    The default value of this property is an empty array.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • shadow shadow Property

    The shadow displayed underneath the view.

    Declaration

    Swift

    @NSCopying var shadow: NSShadow?

    Objective-C

    @property(copy) 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

    The default value of this property is normally nil. When you configure any of the shadow-related properties on the view’s layer, such as the shadowColor,shadowOffset, shadowOpacity or shadowRadius properties, this property contains the NSShadow object that encapsulates that information. Assigning a new shadow object to this property sets the corresponding shadow-related properties on the view’s layer.

    If the view does not have a layer, setting the value of this property has no effect.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Updates the view’s content by modifying its underlying layer.

    Declaration

    Swift

    func updateLayer()

    Objective-C

    - (void)updateLayer

    Discussion

    You use this method to optimize the rendering of your view in situations where you can represent your views contents entirely using a layer object. If your view’s wantsUpdateLayer property is YEStrue, the view calls this method instead of drawRect: during the view update cycle. Custom views can override this method and use it to modify the properties of the underlying layer object. Modifying layer properties is a much more efficient way to update your view than is redrawing its content each time something changes.

    When you want to update the contents of your layer, mark the view as dirty by calling its setNeedsDisplay: method with a value of YEStrue. Doing so adds the view to the list of views that need to be refreshed during the next update cycle. During that update cycle, this method is called if thewantsUpdateLayer property is still YEStrue.

    Your implementation of this method should not call super.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.8 and later.

    See Also

    wantsUpdateLayer

  • Overridden by subclasses to draw the receiver’s image within the specified rectangle.

    Declaration

    Swift

    func drawRect(_ dirtyRect: NSRect)

    Objective-C

    - (void)drawRect:(NSRect)dirtyRect

    Parameters

    dirtyRect

    A rectangle defining the portion of the view that requires redrawing. This rectangle usually represents the portion of the view that requires updating. When responsive scrolling is enabled, this rectangle can also represent a nonvisible portion of the view that AppKit wants to cache.

    Discussion

    Use this method to draw the specified portion of your view’s content. Your implementation of this method should be as fast as possible and do as little work as possible. The dirtyRect parameter helps you achieve better performance by specifying the portion of the view that needs to be drawn. You should always limit drawing to the content inside this rectangle. For even better performance, you can call the getRectsBeingDrawn:count: method and use the list of rectangles returned by that method to limit drawing even further. You can also use the needsToDrawRect: method test whether objects in a particular rectangle need to be drawn.

    The default implementation does nothing. Subclasses should override this method if they do custom drawing. Prior to calling this method, AppKit creates an appropriate drawing context and configures it for drawing to the view; you do not need to configure the drawing context yourself. If your app manages content using its layer object instead, use the updateLayer method to update your layer instead of overriding this method.

    If your custom view is a direct NSView subclass, you do not need to call super. For all other views, call super at some point in your implementation so that the parent class can perform any additional drawing.

    For information about how to draw in your app, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • canDraw canDraw Property

    A Boolean value indicating whether drawing commands will produce any results. (read-only)

    Declaration

    Swift

    var canDraw: Bool { get }

    Objective-C

    @property(readonly) BOOL canDraw

    Discussion

    The value of this property is YEStrue when drawing produces expected results. A view object can draw onscreen 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 also draw during printing if it is a descendant of the view being printed.

    Check the value of this property before attempting to force drawing to a specific context. For example, if the value of this property is NOfalse, do not call lockFocus or do issue any drawing commands from the view. You do not need to check whether drawing can occur when calling the display method or any of its related methods. The display methods perform appropriate checks before asking the view to draw itself.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    hidden

  • A Boolean value indicating whether the view can draw its contents on a background thread.

    Declaration

    Swift

    var canDrawConcurrently: Bool

    Objective-C

    @property BOOL canDrawConcurrently

    Discussion

    If your view’s drawRect: implementation can draw safely on a background thread, set this property to YEStrue. Doing so gives AppKit the ability to run your view’s drawing code off the app’s main thread, which can improve performance. The view's window must also have its allowsConcurrentViewDrawing property set to YEStrue (the default) for threaded view drawing to occur.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • The portion of the view that is not clipped by its superviews. (read-only)

    Declaration

    Swift

    var visibleRect: NSRect { get }

    Objective-C

    @property(readonly) NSRect visibleRect

    Discussion

    Visibility, as reflected by this property, does not account for whether other view or window objects overlap the current view or whether the current view is installed in a window at all. This value of this property is NSZeroRect if the current view is effectively hidden.

    During a printing operation the visible rectangle is further clipped to the page being imaged.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    hidden
    isVisible (NSWindow)
    documentVisibleRect (NSScrollView)
    documentVisibleRect (NSClipView)

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

    Declaration

    Swift

    func getRectsBeingDrawn(_ rects: UnsafeMutablePointer<UnsafePointer<NSRect>>, count count: UnsafeMutablePointer<Int>)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func needsToDrawRect(_ aRect: NSRect) -> Bool

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value indicating whether AppKit’s default clipping behavior is in effect. (read-only)

    Declaration

    Swift

    var wantsDefaultClipping: Bool { get }

    Objective-C

    @property(readonly) BOOL wantsDefaultClipping

    Return Value

    YEStrue if the default clipping is in effect, NOfalse otherwise. By default, this method returns YEStrue.

    Discussion

    The default value of this property is YEStrue. When the value of this property is YEStrue, AppKit sets the current clipping region to the bounds of the view prior to calling that view’s drawRect: method. Subclasses may override this property and return NOfalse to suppress this default clipping behavior. You might do this to avoid the cost of setting up, enforcing, and cleaning up the clipping path. If you do change the value to NOfalse, you are responsible for doing your own clipping or constraining drawing appropriately. Failure to do so could the view to corrupt the contents of other views in the window.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func bitmapImageRepForCachingDisplayInRect(_ aRect: NSRect) -> NSBitmapImageRep?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func cacheDisplayInRect(_ rect: NSRect, toBitmapImageRep bitmapImageRep: NSBitmapImageRep)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func print(_ sender: AnyObject?)

    Objective-C

    - (void)print:(id)sender

    Parameters

    sender

    The object that sent the message.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func beginPageInRect(_ aRect: NSRect, atPlacement location: NSPoint)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func dataWithEPSInsideRect(_ aRect: NSRect) -> NSData

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func dataWithPDFInsideRect(_ aRect: NSRect) -> NSData

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The view’s print job title. (read-only)

    Declaration

    Swift

    var printJobTitle: String { get }

    Objective-C

    @property(readonly, copy) NSString *printJobTitle

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A default header string that includes the print job title and date. (read-only)

    Declaration

    Swift

    @NSCopying var pageHeader: NSAttributedString { get }

    Objective-C

    @property(readonly, copy) NSAttributedString *pageHeader

    Discussion

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

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    pageFooter

  • A default footer string that includes the current page number and page count. (read-only)

    Declaration

    Swift

    @NSCopying var pageFooter: NSAttributedString { get }

    Objective-C

    @property(readonly, copy) NSAttributedString *pageFooter

    Discussion

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

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    pageHeader

  • Writes EPS data that draws the region of the receiver within a specified rectangle onto a pasteboard.

    Declaration

    Swift

    func writeEPSInsideRect(_ aRect: NSRect, toPasteboard pboard: NSPasteboard)

    Objective-C

    - (void)writeEPSInsideRect:(NSRect)aRect toPasteboard:(NSPasteboard *)pboard

    Parameters

    aRect

    A rectangle defining the region.

    pboard

    An object representing a pasteboard.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Writes PDF data that draws the region of the receiver within a specified rectangle onto a pasteboard.

    Declaration

    Swift

    func writePDFInsideRect(_ aRect: NSRect, toPasteboard pboard: NSPasteboard)

    Objective-C

    - (void)writePDFInsideRect:(NSRect)aRect toPasteboard:(NSPasteboard *)pboard

    Parameters

    aRect

    A rectangle defining the region.

    pboard

    An object representing a pasteboard.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func drawPageBorderWithSize(_ borderSize: NSSize)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func drawSheetBorderWithSize(_ borderSize: NSSize)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The fraction 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. (read-only)

    Declaration

    Swift

    var heightAdjustLimit: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat heightAdjustLimit

    Discussion

    The value of this property is a floating point number in the range 0.0 to 1.0. This fraction is used to calculate the bottom edge limit for an adjustPageHeightNew:top:bottom:limit: message.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    widthAdjustLimit

  • The fraction of the page that can be pushed onto the next page during automatic pagination to prevent items such as small images or text columns from being divided across pages. (read-only)

    Declaration

    Swift

    var widthAdjustLimit: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat widthAdjustLimit

    Discussion

    The value of this property is a floating point number in the range 0.0 to 1.0. This fraction is used to calculate the right edge limit for a adjustPageWidthNew:left:right:limit: message.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Overridden by subclasses to adjust page width during automatic pagination.

    Declaration

    Swift

    func adjustPageWidthNew(_ newRight: UnsafeMutablePointer<CGFloat>, left left: CGFloat, right proposedRight: CGFloat, limit rightLimit: CGFloat)

    Objective-C

    - (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 value of the widthAdjustLimit property.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Overridden by subclasses to adjust page height during automatic pagination.

    Declaration

    Swift

    func adjustPageHeightNew(_ newBottom: UnsafeMutablePointer<CGFloat>, top top: CGFloat, bottom proposedBottom: CGFloat, limit bottomLimit: CGFloat)

    Objective-C

    - (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 value of the heightAdjustLimit property.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns YEStrue if the receiver handles page boundaries, NOfalse otherwise.

    Declaration

    Swift

    func knowsPageRange(_ aRange: NSRangePointer) -> Bool

    Objective-C

    - (BOOL)knowsPageRange:(NSRangePointer)aRange

    Parameters

    aRange

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

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func rectForPage(_ pageNumber: Int) -> NSRect

    Objective-C

    - (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 YEStrue 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 NOfalse to knowsPageRange:, this method isn’t invoked by the printing mechanism.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func locationOfPrintRect(_ aRect: NSRect) -> NSPoint

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var needsDisplay: Bool

    Objective-C

    @property BOOL needsDisplay

    Parameters

    flag

    If YEStrue, marks the receiver’s entire bounds as needing display; if NOfalse, 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.)

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func setNeedsDisplayInRect(_ invalidRect: NSRect)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value indicating whether the view needs to be redrawn before being displayed.

    Declaration

    Swift

    var needsDisplay: Bool

    Objective-C

    @property BOOL needsDisplay

    Discussion

    The displayIfNeeded... methods check the value of this property to avoid unnecessary drawing, and all display methods set the value back to NOfalse when the view is up to date.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func display()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func displayRect(_ aRect: NSRect)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func displayRectIgnoringOpacity(_ aRect: NSRect)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func displayRectIgnoringOpacity(_ aRect: NSRect, inContext context: NSGraphicsContext)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Displays the receiver and all its subviews if any part of the receiver has been marked as needing display.

    Declaration

    Swift

    func displayIfNeeded()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func displayIfNeededInRect(_ aRect: NSRect)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func displayIfNeededIgnoringOpacity()

    Objective-C

    - (void)displayIfNeededIgnoringOpacity

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func displayIfNeededInRectIgnoringOpacity(_ aRect: NSRect)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Translates the display rectangles by the specified delta.

    Declaration

    Swift

    func translateRectsNeedingDisplayInRect(_ clipRect: NSRect, by delta: NSSize)

    Objective-C

    - (void)translateRectsNeedingDisplayInRect:(NSRect)clipRect by:(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

    This method performs the shifting of dirty rectangles that an equivalent scrollRect:by: operation would cause, without performing the actual scroll operation. It is only useful in very rare cases where a view implements its own low-level scrolling mechanics.

    This method:

    1. 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. Marks the resultant rectangles as needing display.

    The developer must ensure that clipRect and delta are pixel-aligned in order to guarantee correct drawing. See Transforming View Coordinates To and From Base Space for a description of how to pixel-align view coordinates.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • opaque opaque Property

    A Boolean value indicating whether the view fills its frame rectangle with opaque content. (read-only)

    Declaration

    Swift

    var opaque: Bool { get }

    Objective-C

    @property(getter=isOpaque, readonly) BOOL opaque

    Discussion

    The default value of this property is NOfalse to reflect the fact that views do no drawing by default. Subclasses can override this property and return YEStrue to indicate that the view completely covers its frame rectangle with opaque content. Doing so can improve performance during drawing operations by eliminating the need to render content behind the view.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • Informs the receiver that it will be required to draw content.

    Declaration

    Swift

    func viewWillDraw()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns a backing store pixel aligned rectangle in window coordinates.

    Declaration

    Swift

    func backingAlignedRect(_ aRect: NSRect, options options: NSAlignmentOptions) -> NSRect

    Objective-C

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

    Parameters

    aRect

    The rectangle in view coordinates.

    options

    The alignment options. See NSAlignmentOptions for possible values.

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Converts a point from its pixel aligned backing store coordinate system to the view’s interior coordinate system.

    Declaration

    Swift

    func convertPointFromBacking(_ aPoint: NSPoint) -> NSPoint

    Objective-C

    - (NSPoint)convertPointFromBacking:(NSPoint)aPoint

    Parameters

    aPoint

    The point in the pixel backing store aligned coordinate system.

    Return Value

    A point in the view’s interior coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Converts a point from the view’s interior coordinate system to its pixel aligned backing store coordinate system.

    Declaration

    Swift

    func convertPointToBacking(_ aPoint: NSPoint) -> NSPoint

    Objective-C

    - (NSPoint)convertPointToBacking:(NSPoint)aPoint

    Parameters

    aPoint

    The point in the view’s interior coordinate system.

    Return Value

    A point in its pixel aligned backing store coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Convert the point from the layer's interior coordinate system to the view’s interior coordinate system.

    Declaration

    Swift

    func convertPointFromLayer(_ aPoint: NSPoint) -> NSPoint

    Objective-C

    - (NSPoint)convertPointFromLayer:(NSPoint)aPoint

    Parameters

    aPoint

    The point in the layer’s interior coordinate system.

    Return Value

    The point in the view’s interior coordinate system.

    Discussion

    The layer's space is virtual, and doesn't take into account the layer's contentsScale setting.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Convert the size from the view’s interior coordinate system to the layer's interior coordinate system.

    Declaration

    Swift

    func convertPointToLayer(_ aPoint: NSPoint) -> NSPoint

    Objective-C

    - (NSPoint)convertPointToLayer:(NSPoint)aPoint

    Parameters

    aPoint

    A point in the view’s interior coordinate system.

    Return Value

    A point in the view’s layer interior coordinate system.

    Discussion

    The layer's space is virtual, and doesn't take into account the layer's contentsScale setting.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func convertRectFromBacking(_ aRect: NSRect) -> NSRect

    Objective-C

    - (NSRect)convertRectFromBacking:(NSRect)aRect

    Parameters

    aRect

    The rectangle in the pixel backing store coordinate system.

    Return Value

    A rectangle in the view’s interior coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func convertRectToBacking(_ aRect: NSRect) -> NSRect

    Objective-C

    - (NSRect)convertRectToBacking:(NSRect)aRect

    Parameters

    aRect

    A rectangle in the view’s interior coordinate system.

    Return Value

    A rectangle in its pixel aligned backing store coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Convert the rectangle from the layer's interior coordinate system to the view’s interior coordinate system.

    Declaration

    Swift

    func convertRectFromLayer(_ aRect: NSRect) -> NSRect

    Objective-C

    - (NSRect)convertRectFromLayer:(NSRect)aRect

    Parameters

    aRect

    A rectangle in the layer's interior coordinate system.

    Return Value

    A rectangle in the view’s interior coordinate system.

    Discussion

    The layer's space is virtual, and doesn't take into account the layer's contentsScale setting.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Convert the size from the view’s interior coordinate system to the layer's interior coordinate system.

    Declaration

    Swift

    func convertRectToLayer(_ aRect: NSRect) -> NSRect

    Objective-C

    - (NSRect)convertRectToLayer:(NSRect)aRect

    Parameters

    aRect

    A rectangle in the view’s interior coordinate system.

    Return Value

    A rectangle in the layer's interior coordinate system.

    Discussion

    The layer's space is virtual, and doesn't take into account the layer's contentsScale setting.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Converts a size from its pixel aligned backing store coordinate system to the view’s interior coordinate system.

    Declaration

    Swift

    func convertSizeFromBacking(_ aSize: NSSize) -> NSSize

    Objective-C

    - (NSSize)convertSizeFromBacking:(NSSize)aSize

    Parameters

    aSize

    The size in the pixel aligned coordinate coordinate system.

    Return Value

    The size in the view’s interior coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Converts a size from the view’s interior coordinate system to its pixel aligned backing store coordinate system.

    Declaration

    Swift

    func convertSizeToBacking(_ aSize: NSSize) -> NSSize

    Objective-C

    - (NSSize)convertSizeToBacking:(NSSize)aSize

    Parameters

    aSize

    The size in the view’s interior coordinate system.

    Return Value

    The size in the pixel aligned coordinate coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Convert the size from the layer's interior coordinate system to the view’s interior coordinate system.

    Declaration

    Swift

    func convertSizeFromLayer(_ aSize: NSSize) -> NSSize

    Objective-C

    - (NSSize)convertSizeFromLayer:(NSSize)aSize

    Parameters

    aSize

    A size in the layer's interior coordinate system.

    Return Value

    A size in the view’s interior coordinate system.

    Discussion

    The layer's space is virtual, and doesn't take into account the layer's contentsScale setting.

    The returned NSSize values are always forced to have positive a width and height.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Convert the size from the view’s interior coordinate system to the layer's interior coordinate system.

    Declaration

    Swift

    func convertSizeToLayer(_ aSize: NSSize) -> NSSize

    Objective-C

    - (NSSize)convertSizeToLayer:(NSSize)aSize

    Parameters

    aSize

    A size in the view’s interior coordinate system.

    Return Value

    A size in the layer's interior coordinate system.

    Discussion

    The layer's space is virtual, and doesn't take into account the layer's contentsScale setting.

    The returned NSSize values are always forced to have positive a width and height.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func convertPoint(_ aPoint: NSPoint, fromView aView: NSView?) -> NSPoint

    Objective-C

    - (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. Both aView and the receiver must belong to the same NSWindow object, and that window must not be nil. If aView is nil, this method converts from window coordinates instead.

    Return Value

    The point converted to the coordinate system of the receiver.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func convertPoint(_ aPoint: NSPoint, toView aView: NSView?) -> NSPoint

    Objective-C

    - (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. Both aView and the receiver must belong to the same NSWindow object, and that window must not be nil. If aView is nil, this method converts to window coordinates instead.

    Return Value

    The point converted to the coordinate system of aView.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func convertSize(_ aSize: NSSize, fromView aView: NSView?) -> NSSize

    Objective-C

    - (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. Both aView and the receiver must belong to the same NSWindow object, and that window must not be nil. If aView is nil, this method converts from window coordinates instead.

    Return Value

    The converted size, as an NSSize structure.

    Discussion

    The returned NSSize values are always forced to have positive a width and height.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func convertSize(_ aSize: NSSize, toView aView: NSView?) -> NSSize

    Objective-C

    - (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. Both aView and the receiver must belong to the same NSWindow object, and that window must not be nil. If aView is nil, this method converts to window coordinates instead.

    Return Value

    The converted size, as an NSSize structure.

    Discussion

    The returned NSSize values are always forced to have positive a width and height.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func convertRect(_ aRect: NSRect, fromView aView: NSView?) -> NSRect

    Objective-C

    - (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. Both aView and the receiver must belong to the same NSWindow object, and that window must not be nil. If aView is nil, this method converts from window coordinates instead.

    Return Value

    The converted rectangle.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func convertRect(_ aRect: NSRect, toView aView: NSView?) -> NSRect

    Objective-C

    - (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. Both aView and the receiver must belong to the same NSWindow object, and that window must not be nil. If aView is nil, this method converts the rectangle to window coordinates instead.

    Return Value

    The converted rectangle.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func centerScanRect(_ aRect: NSRect) -> NSRect

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func translateOriginToPoint(_ newOrigin: NSPoint)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func scaleUnitSquareToSize(_ newUnitSize: NSSize)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func rotateByAngle(_ angle: CGFloat)

    Objective-C

    - (void)rotateByAngle:(CGFloat)angle

    Parameters

    angle

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

    Discussion

    See the boundsRotation 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • flipped flipped Property

    A Boolean value indicating whether the view uses a flipped coordinate system. (read-only)

    Declaration

    Swift

    var flipped: Bool { get }

    Objective-C

    @property(getter=isFlipped, readonly) BOOL flipped

    Discussion

    The default value of this property is NOfalse, which results in a non-flipped coordinate system. In a non-flipped coordinate system, the origin is in the lower-right corner of the view and positive y-values extend upward. In a flipped coordinate system, the origin is in the upper-left corner of the view and y-values extend downward. X-values always extend to the right.

    If you want your view to use a flipped coordinate system, override this property and return YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • A Boolean value indicating whether the view or any of its ancestors has ever had a rotation factor applied to its frame or bounds. (read-only)

    Declaration

    Swift

    var rotatedFromBase: Bool { get }

    Objective-C

    @property(getter=isRotatedFromBase, readonly) BOOL rotatedFromBase

    Discussion

    The value of this property is YEStrue if the view or any of its ancestors has had its frameRotation or boundsRotation properties modified at any time. The value is still YEStrue if the rotation factor is changed to a nonzero value and then back to 0.

    Use this information to optimize drawing and coordinate calculation. Do not use it to reflect the exact state of the receiver’s coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • A Boolean value indicating whether the view or any of its ancestors has ever had a rotation factor applied to its frame or bounds, or has been scaled from the window’s base coordinate system. (read-only)

    Declaration

    Swift

    var rotatedOrScaledFromBase: Bool { get }

    Objective-C

    @property(getter=isRotatedOrScaledFromBase, readonly) BOOL rotatedOrScaledFromBase

    Discussion

    The value of this property is YEStrue if the view or any of its ancestors has had its frameRotation or boundsRotation properties modified at any time. The value is still YEStrue if the rotation factor is changed to a nonzero value and then back to 0.

    Use this information to optimize drawing and coordinate calculation. Do not use it to reflect the exact state of the receiver’s coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • A Boolean value indicating whether the view applies the autoresizing behavior to its subviews when its frame size changes.

    Declaration

    Swift

    var autoresizesSubviews: Bool

    Objective-C

    @property BOOL autoresizesSubviews

    Discussion

    When the value of this property is YEStrue and the view’s frame changes, the view automatically calls the resizeSubviewsWithOldSize: method to facilitate the resizing of its subviews. When the value of this property is NOfalse, the view does not autoresize its subviews.

    The default value of this property is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The options that determine how the view is resized relative to its superview.

    Declaration

    Swift

    var autoresizingMask: NSAutoresizingMaskOptions

    Objective-C

    @property NSAutoresizingMaskOptions autoresizingMask

    Discussion

    The value of this property is an integer bit mask specified by combining the options described in NSAutoresizingMaskOptions. This mask is used by the resizeWithOldSuperviewSize: method when the view needs to be resized.

    If the autoresizing mask is set to NSViewNotSizable (that is, if none of the options are set), the receiver does not resize at all. When more than one option along an axis is set, the resizeWithOldSuperviewSize: method 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 points, the receiver’s frame and right margin are each widened by 5.0 points.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func resizeSubviewsWithOldSize(_ oldBoundsSize: NSSize)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func resizeWithOldSuperviewSize(_ oldBoundsSize: NSSize)

    Objective-C

    - (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 specified by the autoresizingMask property. You shouldn’t invoke this method directly, but you can override it to define a specific resizing behavior.

    If you override this method and call super as part of your implementation, you should be sure to call super before making changes to the receiving view’s frame yourself.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The constraints held by the view. (read-only)

    Declaration

    Swift

    var constraints: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *constraints

    Discussion

    This property contains an array of NSLayoutConstraint objects representing the constraints applied to the view. If the view does not have any constraints, this property contains an empty array.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Adds a constraint on the layout of the receiving view or its subviews.

    Declaration

    Swift

    func addConstraint(_ constraint: NSLayoutConstraint)

    Objective-C

    - (void)addConstraint:(NSLayoutConstraint *)constraint

    Parameters

    constraint

    The constraint to be added to the view. The constraint may only reference the view itself or its subviews.

    Discussion

    The constraint must involve only views that are within scope of the receiving view. Specifically, any views involved must be either the receiving view itself, or a subview of the receiving view. Constraints that are added to a view are said to be held by that view. The coordinate system used when evaluating the constraint is the coordinate system of the view that holds the constraint.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Adds multiple constraints on the layout of the receiving view or its subviews.

    Declaration

    Swift

    func addConstraints(_ constraints: [AnyObject])

    Objective-C

    - (void)addConstraints:(NSArray *)constraints

    Parameters

    constraints

    An array of constraints to be added to the view. All constraints may only reference the view itself or its subviews.

    Discussion

    All constraints must involve only views that are within scope of the receiving view. Specifically, any views involved must be either the receiving view itself, or a subview of the receiving view. Constraints that are added to a view are said to be held by that view. The coordinate system used when evaluating each constraint is the coordinate system of the view that holds the constraint.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Removes the specified constraint from the view.

    Declaration

    Swift

    func removeConstraint(_ constraint: NSLayoutConstraint)

    Objective-C

    - (void)removeConstraint:(NSLayoutConstraint *)constraint

    Parameters

    constraint

    The constraint to remove. Removing a constraint not held by the view has no effect.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Removes the specified constraints from the view.

    Declaration

    Swift

    func removeConstraints(_ constraints: [AnyObject])

    Objective-C

    - (void)removeConstraints:(NSArray *)constraints

    Parameters

    constraints

    The constraints to remove.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The minimum size of the view that satisfies the constraints it holds. (read-only)

    Declaration

    Swift

    var fittingSize: NSSize { get }

    Objective-C

    @property(readonly) NSSize fittingSize

    Discussion

    AppKit sets this property to the best size available for the view, considering all of the constraints it and its subviews hold and satisfying a preference to make the view as small as possible. The size values in this property are never negative.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

    See Also

    NSLayoutPriorityFittingSizeCompression

  • The natural size for the receiving view, considering only properties of the view itself. (read-only)

    Declaration

    Swift

    var intrinsicContentSize: NSSize { get }

    Objective-C

    @property(readonly) NSSize intrinsicContentSize

    Return Value

    A size indicating the natural size for the receiving view based on its intrinsic properties.

    Discussion

    The default width and height values of this property are set to NSViewNoInstrinsicMetric. For a custom view, you can override this property and use it to communicate what size you would like your view to be based on its content. You might do this in cases where the layout system cannot determine the size of the view based solely on its current constraints. For example, a text field might override this method and return an intrinsic size based on the text it contains. The intrinsic size you supply must be independent of the content frame, because there’s no way to dynamically communicate a changed width to the layout system based on a changed height. If your custom view has no intrinsic size for a given dimension, you can set the corresponding dimension to the NSViewNoInstrinsicMetric.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Invalidates the view’s intrinsic content size.

    Declaration

    Swift

    func invalidateIntrinsicContentSize()

    Objective-C

    - (void)invalidateIntrinsicContentSize

    Discussion

    Call this when something changes in your custom view that invalidates its intrinsic content size. This allows the constraint-based layout system to take the new intrinsic content size into account in its next layout pass.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the priority with which a view resists being made smaller than its intrinsic size.

    Declaration

    Swift

    func contentCompressionResistancePriorityForOrientation(_ orientation: NSLayoutConstraintOrientation) -> NSLayoutPriority

    Objective-C

    - (NSLayoutPriority)contentCompressionResistancePriorityForOrientation:(NSLayoutConstraintOrientation)orientation

    Parameters

    orientation

    The orientation of the dimension of the view that might be reduced.

    Return Value

    The priority with which the view should resist being compressed from its intrinsic size in the specified orientation.

    Discussion

    The constraint-based layout system uses these priorities when determining the best layout for views that are encountering constraints that would require them to be smaller than their intrinsic size.

    Subclasses should not override this method. Instead, custom views should set default values for their content on creation, typically to NSLayoutPriorityDefaultLow or NSLayoutPriorityDefaultHigh.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Sets the priority with which a view resists being made smaller than its intrinsic size.

    Declaration

    Swift

    func setContentCompressionResistancePriority(_ priority: NSLayoutPriority, forOrientation orientation: NSLayoutConstraintOrientation)

    Objective-C

    - (void)setContentCompressionResistancePriority:(NSLayoutPriority)priority forOrientation:(NSLayoutConstraintOrientation)orientation

    Parameters

    priority

    The new priority.

    orientation

    The orientation for which the compression resistance priority should be set.

    Discussion

    Custom views should set default values for both orientations on creation, based on their content, typically to NSLayoutPriorityDefaultLow or NSLayoutPriorityDefaultHigh. When creating user interfaces, the layout designer can modify these priorities for specific views when the overall layout design requires different tradeoffs than the natural priorities of the views being used in the interface.

    Subclasses should not override this method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the priority with which a view resists being made larger than its intrinsic size.

    Declaration

    Swift

    func contentHuggingPriorityForOrientation(_ orientation: NSLayoutConstraintOrientation) -> NSLayoutPriority

    Objective-C

    - (NSLayoutPriority)contentHuggingPriorityForOrientation:(NSLayoutConstraintOrientation)orientation

    Parameters

    orientation

    The orientation of the dimension of the view that might be enlarged.

    Return Value

    The priority with which the view should resist being enlarged from its intrinsic size in the specified orientation.

    Discussion

    The constraint-based layout system uses these priorities when determining the best layout for views that are encountering constraints that would require them to be larger than their intrinsic size.

    Subclasses should not override this method. Instead, custom views should set default values for their content on creation, typically to NSLayoutPriorityDefaultLow or NSLayoutPriorityDefaultHigh.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Sets the priority with which a view resists being made larger than its intrinsic size.

    Declaration

    Swift

    func setContentHuggingPriority(_ priority: NSLayoutPriority, forOrientation orientation: NSLayoutConstraintOrientation)

    Objective-C

    - (void)setContentHuggingPriority:(NSLayoutPriority)priority forOrientation:(NSLayoutConstraintOrientation)orientation

    Parameters

    priority

    The new priority.

    orientation

    The orientation for which the content hugging priority should be set.

    Discussion

    Custom views should set default values for both orientations on creation, based on their content, typically to NSLayoutPriorityDefaultLow or NSLayoutPriorityDefaultHigh. When creating user interfaces, the layout designer can modify these priorities for specific views when the overall layout design requires different tradeoffs than the natural priorities of the views being used in the interface.

    Subclasses should not override this method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the view’s alignment rectangle for a given frame.

    Declaration

    Swift

    func alignmentRectForFrame(_ frame: NSRect) -> NSRect

    Objective-C

    - (NSRect)alignmentRectForFrame:(NSRect)frame

    Parameters

    frame

    The frame whose corresponding alignment rectangle is desired.

    Return Value

    The alignment rectangle for the specified frame.

    Discussion

    The constraint-based layout system uses alignment rectangles to align views, rather than their frame. This allows custom views to be aligned based on the location of their content while still having a frame that encompasses any ornamentation they need to draw around their content, such as shadows or reflections.

    The default implementation returns the view’s frame modified by the insets specified by the view’s alignmentRectInsets method. Most custom views can override alignmentRectInsets to specify the location of their content within their frame. Custom views that require arbitrary transformations can override alignmentRectForFrame: and frameForAlignmentRect: to describe the location of their content. These two methods must always be inverses of each other.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the view’s frame for a given alignment rectangle.

    Declaration

    Swift

    func frameForAlignmentRect(_ alignmentRect: NSRect) -> NSRect

    Objective-C

    - (NSRect)frameForAlignmentRect:(NSRect)alignmentRect

    Parameters

    alignmentRect

    The alignment rectangle whose corresponding frame is desired.

    Return Value

    The frame for the specified alignment rectangle

    Discussion

    The constraint-based layout system uses alignment rectangles to align views, rather than their frame. This allows custom views to be aligned based on the location of their content while still having a frame that encompasses any ornamentation they need to draw around their content, such as shadows or reflections.

    The default implementation returns alignmentRect modified by the insets specified by the view’s alignmentRectInsets method. Most custom views can override alignmentRectInsets to specify the location of their content within their frame. Custom views that require arbitrary transformations can override alignmentRectForFrame: and frameForAlignmentRect: to describe the location of their content. These two methods must always be inverses of each other.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The insets (in points) from the view’s frame that define its content rectangle. (read-only)

    Declaration

    Swift

    var alignmentRectInsets: NSEdgeInsets { get }

    Objective-C

    @property(readonly) NSEdgeInsets alignmentRectInsets

    Discussion

    The default value is an NSEdgeInsets structure with the value 0 for each component. Custom views that draw ornamentation around their content can override this property and return insets that align with the edges of the content, excluding the ornamentation. This allows the constraint-based layout system to align views based on their content, rather than just their frame.

    Custom views whose content location can’t be expressed by a simple set of insets should override alignmentRectForFrame: and frameForAlignmentRect: to describe their custom transform between alignment rectangle and frame.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The distance (in points) between the bottom of the view’s alignment rectangle and its baseline. (read-only)

    Declaration

    Swift

    var baselineOffsetFromBottom: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat baselineOffsetFromBottom

    Discussion

    The default value of this property is 0. For views that contain text or other content whose layout benefits from having a custom baseline, you can override this property and provide the correct distance between the bottom of the view’s alignment rectangle and that baseline.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • A Boolean value indicating whether the view needs a layout pass before it can be drawn.

    Declaration

    Swift

    var needsLayout: Bool

    Objective-C

    @property BOOL needsLayout

    Return Value

    YEStrue if the view needs a layout pass, NOfalse otherwise.

    Discussion

    You only ever need to change the value of this property if your view implements the layout method because it has custom layout that is not expressible in the constraint-based layout system. Setting this property to YEStrue lets the system know that the view’s layout needs to be updated before it is drawn. The system checks the value of this property prior to applying constraint-based layout rules for the view.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Perform layout in concert with the constraint-based layout system.

    Declaration

    Swift

    func layout()

    Objective-C

    - (void)layout

    Discussion

    Override this method if your custom view needs to perform custom layout not expressible using the constraint-based layout system. In this case you are responsible for calling setNeedsLayout: when something that impacts your custom layout changes.

    You may not invalidate any constraints as part of your layout phase, nor invalidate the layout of your superview or views outside of your view hierarchy. You also may not invoke a drawing pass as part of layout.

    You must call [super layout] as part of your implementation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Updates the layout of the receiving view and its subviews based on the current views and constraints.

    Declaration

    Swift

    func layoutSubtreeIfNeeded()

    Objective-C

    - (void)layoutSubtreeIfNeeded

    Discussion

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

    Subclasses should not override this method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • A Boolean value indicating whether the view’s constraints need to be updated.

    Declaration

    Swift

    var needsUpdateConstraints: Bool

    Objective-C

    @property BOOL needsUpdateConstraints

    Discussion

    When a property of your view changes in a way that would impact constraints, set the value of this property to YEStrue to indicate that the constraints need to be updated at some point in the future. The next time the layout process happens, the constraint-based layout system uses the value of this property to determine whether it needs to call updateConstraints on the view.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Update constraints for the view.

    Declaration

    Swift

    func updateConstraints()

    Objective-C

    - (void)updateConstraints

    Discussion

    Custom views that set up constraints themselves should do so by overriding this method. When your custom view notes that a change has been made to the view that invalidates one of its constraints, it should immediately remove that constraint, and update the needsUpdateConstraints property to note that constraints need to be updated. Before layout is performed, your implementation of updateConstraints will be invoked, allowing you to verify that all necessary constraints for your content are in place at a time when your custom view’s properties are not changing.

    You may not invalidate any constraints as part of your constraint update phase. You also may not invoke a layout or drawing phase as part of constraint updating.

    You must call [super updateConstraints] at the end of your implementation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Updates the constraints for the receiving view and its subviews.

    Declaration

    Swift

    func updateConstraintsForSubtreeIfNeeded()

    Objective-C

    - (void)updateConstraintsForSubtreeIfNeeded

    Discussion

    Whenever a new layout pass is triggered for a view, the system invokes this method to ensure that any constraints for the view and its subviews are updated with information from the current view hierarchy and its constraints. This method is called automatically by the system, but may be invoked manually if you need to examine the most up to date constraints.

    Subclasses should not override this method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns whether the receiver depends on the constraint-based layout system.

    Declaration

    Swift

    class func requiresConstraintBasedLayout() -> Bool

    Objective-C

    + (BOOL)requiresConstraintBasedLayout

    Return Value

    YEStrue if the view must be in a window using constraint-based layout to function properly, NOfalse otherwise.

    Discussion

    Custom views should override this to return YEStrue if they can not layout correctly using autoresizing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • A Boolean value indicating whether the view’s autoresizing mask is translated into constraints for the constraint-based layout system.

    Declaration

    Swift

    var translatesAutoresizingMaskIntoConstraints: Bool

    Objective-C

    @property BOOL translatesAutoresizingMaskIntoConstraints

    Discussion

    When this property is set to YEStrue, the view’s superview looks at the view’s autoresizing mask, produces constraints that implement it, and adds those constraints to itself (the superview). If your view has flexible constraints that require dynamic adjustment, set this property to NOfalse and apply the constraints yourself.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

See Auto Layout Guide for more details on debugging constraint-based layout.

  • Returns the constraints impacting the layout of the view for a given orientation.

    Declaration

    Swift

    func constraintsAffectingLayoutForOrientation(_ orientation: NSLayoutConstraintOrientation) -> [AnyObject]

    Objective-C

    - (NSArray *)constraintsAffectingLayoutForOrientation:(NSLayoutConstraintOrientation)orientation

    Parameters

    orientation

    The direction of the dimension for which the constraints should be found.

    Return Value

    The constraints impacting the layout of the view for the specified orientation.

    Discussion

    The returned set of constraints may not all include the view explicitly. Constraints that impact the location of the view implicitly may also be included. While this provides a good starting point for debugging, there is no guarantee that the returned set of constraints will include all of the constraints that have an impact on the view’s layout in the given orientation.

    This method should only be used for debugging constraint-based layout. No application should ship with calls to this method as part of its operation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • A Boolean value indicating whether the constraints impacting the layout of the view incompletely specify the location of the view. (read-only)

    Declaration

    Swift

    var hasAmbiguousLayout: Bool { get }

    Objective-C

    @property(readonly) BOOL hasAmbiguousLayout

    Discussion

    The value of this property is YEStrue when the view’s location or size cannot be determined definitively based on the current constraints.

    Accessing this property engages the layout engine to determine whether any other frame would also satisfy the constraints on the view. Because this process involves laying out the view, accessing the property can be an expensive operation but it can also provide useful debugging information. AppKit automatically calls this method when a window is asked to visualize its constraints using the visualizeConstraints: method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Randomly changes the frame of a view with an ambiguous layout between the different valid values.

    Declaration

    Swift

    func exerciseAmbiguityInLayout()

    Objective-C

    - (void)exerciseAmbiguityInLayout

    Discussion

    This method randomly changes the frame of a view with an ambiguous layout between its different valid values, causing the view to move in the interface. This makes it easy to visually identify what the valid frames are and may enable the developer to discern what constraints need to be added to the layout to fully specify a location for the view.

    This method should only be used for debugging constraint-based layout. No application should ship with calls to this method as part of its operation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func lockFocus()

    Objective-C

    - (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. This method throws an exception if the view is hidden or if drawing cannot happen for some other reason. To ensure that you can lock focus successfully, make sure the canDraw property is YEStrue; you can also call lockFocusIfCanDraw instead and use the return value of that method to determine if focus was obtained successfully.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func lockFocusIfCanDraw() -> Bool

    Objective-C

    - (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 NOfalse, when the receiver is hidden and the current context is drawing to the screen (as opposed to a printing context).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func lockFocusIfCanDrawInContext(_ context: NSGraphicsContext) -> Bool

    Objective-C

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

    YEStrue if successful; otherwise, returns NOfalse.

    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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Unlocks focus from the current view.

    Declaration

    Swift

    func unlockFocus()

    Objective-C

    - (void)unlockFocus

    Discussion

    Call this method after a previous call to the lockFocus, lockFocusIfCanDraw, or lockFocusIfCanDrawInContext: method of this view object. Doing so releases focus from the current view and returns it back to the previously focused view, if any. This method raises an NSInvalidArgumentException if the current view does not have the focus.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func focusView() -> NSView?

    Objective-C

    + (NSView *)focusView

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The type of focus ring drawn around the receiver.

    Declaration

    Swift

    var focusRingType: NSFocusRingType

    Objective-C

    @property NSFocusRingType focusRingType

    Return Value

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

    Discussion

    Use this property to specify the type of focus ring to draw. For a list of possible values, see NSFocusRingType.

    To disable drawing of a view’s focus ring, set the value of this property to NSFocusRingTypeNone. You should only disable the default drawing of a view’s focus ring when you want the view to draw its own focus ring. For example, you might disable focus ring drawing when the view uses its background color to indicate focus or when the view does not have sufficient space to display a focus ring.

    Changing the value in this property 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • The focus ring mask bounds, specified in the view’s coordinate space. (read-only)

    Declaration

    Swift

    var focusRingMaskBounds: NSRect { get }

    Objective-C

    @property(readonly) NSRect focusRingMaskBounds

    Discussion

    The rectangle in this property is specified relative to the view’s interior (bounds) coordinate space. The mask bounds allows the focus ring’s overall size and position to be determined before it is drawn. Override this property if your view requires the display of a focus ring. The default value of this property is NSZeroRect.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Draws the focus ring mask for the view.

    Declaration

    Swift

    func drawFocusRingMask()

    Objective-C

    - (void)drawFocusRingMask

    Discussion

    This method provides the shape of the focus ring mask by drawing the focus ring mask. An implementation of this method should draw in the view’s interior (bounds) coordinate space, that the focus ring style has been set (it will be set it to NSFocusRingOnly to capture the focus ring itself), and that the fill and stroke colors have been set to an arbitrary fully opaque color.

    Subclasses that find the default behavior insufficient should only draw the focus ring shape.

    The NSView implementation of this method simply fills [self bounds].

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Invoked to notify the view that the focus ring mask requires updating.

    Declaration

    Swift

    func noteFocusRingMaskChanged()

    Objective-C

    - (void)noteFocusRingMaskChanged

    Discussion

    It is important to note that it is only necessary for developers to invoke this method when some internal state change of their application, that the Application Kit can’t determine, affects the shape of the focus ring mask.

    It is assumed that if the view is marked as needing display, or is resized, its focus ring shape is likely to have changed, and there is no need for clients to explicitly send this message in such cases, they are handled automatically.

    If, however, a view is showing a focus ring around some part of its content (an NSImage, perhaps), and that content changes, the client must provide notification by invoking this method so that focusRingMaskBounds and drawFocusRingMask will be invoked to redraw the focus ring.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Invalidates the area around the focus ring.

    Declaration

    Swift

    func setKeyboardFocusRingNeedsDisplayInRect(_ rect: NSRect)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.1 and later.

  • Returns the default focus ring type.

    Declaration

    Swift

    class func defaultFocusRingType() -> NSFocusRingType

    Objective-C

    + (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 the value in the focusRingType property is NSFocusRingTypeDefault, the view can call this class method to find out what type of focus ring is the default. The view is free to ignore the default setting.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value indicating whether the view ensures it is vibrant on top of other content. (read-only)

    Declaration

    Swift

    var allowsVibrancy: Bool { get }

    Objective-C

    @property(readonly) BOOL allowsVibrancy

    Discussion

    AppKit checks this property when the view is incorporated into a view hierarchy that uses vibrancy. If the property is YEStrue, the view takes appropriate measures to ensure its content is vibrant on top of any underlying material. The default value of this property is NOfalse. However, some of AppKit’s view subclasses change the value of this property based on the artwork they draw.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • hidden hidden Property

    A Boolean value indicating whether the view is hidden.

    Declaration

    Swift

    var hidden: Bool

    Objective-C

    @property(getter=isHidden) BOOL hidden

    Discussion

    This property reflects the state of the current view only, as set in Interface Builder or through the most recent change to this property. The property does not account for the state of the receiver’s ancestors in the view hierarchy. Thus, if the view has a hidden ancestor, the value of this property may still be NOfalse even though the view itself is not visible. To determine whether a view is effectively hidden, for whatever reason, get the value of the hiddenOrHasHiddenAncestor property instead.

    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. AppKit 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 this property.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • A Boolean value indicating whether the view is hidden from sight because it, or one of its ancestors, is marked as hidden. (read-only)

    Declaration

    Swift

    var hiddenOrHasHiddenAncestor: Bool { get }

    Objective-C

    @property(getter=isHiddenOrHasHiddenAncestor, readonly) BOOL hiddenOrHasHiddenAncestor

    Discussion

    The value of this property is YEStrue if the value of the hidden property is YEStrue for the current view or any of its ancestors in the view hierarchy. This property 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

    See Also

    hidden

  • Invoked when the receiver is hidden, either directly, or in response to an ancestor being hidden.

    Declaration

    Swift

    func viewDidHide()

    Objective-C

    - (void)viewDidHide

    Discussion

    The receiver receives this message when its hiddenOrHasHiddenAncestor property changes from NOfalse to YEStrue. This happens when the view or an ancestor is marked as hidden, or when the view or an ancestor is inserted into a new view hierarchy.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Invoked when the receiver is unhidden, either directly, or in response to an ancestor being unhidden

    Declaration

    Swift

    func viewDidUnhide()

    Objective-C

    - (void)viewDidUnhide

    Discussion

    The receiver receives this message when its isHiddenOrHasHiddenAncestor state goes from YEStrue to NOfalse.  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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • A Boolean value indicating whether the view is being rendered as part of a live resizing operation. (read-only)

    Declaration

    Swift

    var inLiveResize: Bool { get }

    Objective-C

    @property(readonly) BOOL inLiveResize

    Discussion

    AppKit sets the value of this property to YEStrue when a live resizing operation involving the view is underway. Use this property to determine when to optimize your view’s drawing behavior. Typically, you access this property from your drawRect: method and use the value to change the fidelity of the content you draw, or to draw your content more efficiently.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.1 and later.

  • A Boolean value indicating whether the view optimizes live-resize operations by preserving content that has not moved. (read-only)

    Declaration

    Swift

    var preservesContentDuringLiveResize: Bool { get }

    Objective-C

    @property(readonly) BOOL preservesContentDuringLiveResize

    Discussion

    The default value of this property is NOfalse. If your view supports content preservation, override this property and return YEStrue. 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 the setFrameSize: method 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func getRectsExposedDuringLiveResize(_ exposedRects: UnsafeMutablePointer<NSRect>, count count: UnsafeMutablePointer<Int>)

    Objective-C

    - (void)getRectsExposedDuringLiveResize:(NSRect [4])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 the preservesContentDuringLiveResize property in your view and have your implementation return YEStrue.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The rectangle identifying the portion of your view that did not change during a live resize operation. (read-only)

    Declaration

    Swift

    var rectPreservedDuringLiveResize: NSRect { get }

    Objective-C

    @property(readonly) NSRect rectPreservedDuringLiveResize

    Discussion

    The rectangle in this property 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 rectangle will be empty. To support content preservation, override the preservesContentDuringLiveResize property in your view and have your implementation return YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Informs the receiver of the start of a live resize.

    Declaration

    Swift

    func viewWillStartLiveResize()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.1 and later.

  • Informs the receiver of the end of a live resize.

    Declaration

    Swift

    func viewDidEndLiveResize()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.1 and later.

  • The gesture recognize objects currently attached to the view.

    Declaration

    Swift

    var gestureRecognizers: [AnyObject]

    Objective-C

    @property(copy) NSArray *gestureRecognizers

    Discussion

    The objects in the array are concrete implementations of the NSGestureRecognizer class. If the view has no attached gesture recognizers, the array is empty.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • Attaches a gesture recognizer to the view.

    Declaration

    Swift

    func addGestureRecognizer(_ gestureRecognizer: NSGestureRecognizer)

    Objective-C

    - (void)addGestureRecognizer:(NSGestureRecognizer *)gestureRecognizer

    Parameters

    gestureRecognizer

    The gesture recognizer to attach to the view. This parameter must not be nil.

    Discussion

    Attaching a gesture recognizer to a view defines the scope of the represented gesture, causing it to receive touches occurring only in the view or one of its subviews. The view establishes a strong reference to the specified gesture recognizer.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • Detaches a gesture recognizer from the view.

    Declaration

    Swift

    func removeGestureRecognizer(_ gestureRecognizer: NSGestureRecognizer)

    Objective-C

    - (void)removeGestureRecognizer:(NSGestureRecognizer *)gestureRecognizer

    Parameters

    gestureRecognizer

    The gesture recognizer to remove. This parameter must not be nil.

    Discussion

    Removing a gesture recognizer also removes the strong reference to it held by the view.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Swift

    func acceptsFirstMouse(_ theEvent: NSEvent) -> Bool

    Objective-C

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

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

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

    Declaration

    Swift

    func hitTest(_ aPoint: NSPoint) -> NSView?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func mouse(_ aPoint: NSPoint, inRect aRect: NSRect) -> Bool

    Objective-C

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

    YEStrue if aRect contains aPoint, NOfalse 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func performKeyEquivalent(_ theEvent: NSEvent) -> Bool

    Objective-C

    - (BOOL)performKeyEquivalent:(NSEvent *)theEvent

    Parameters

    theEvent

    The key-down event object representing a key equivalent.

    Return Value

    YEStrue if theEvent is a key equivalent that the receiver handled, NOfalse 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 YEStrue. 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 NOfalse if none of the receiver’s subviews responds YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    keyDown: (NSWindow)

  • Informs the receiver that the user has pressed the right mouse button.

    Declaration

    Objective-C

    - (void)rightMouseDown:(NSEvent *)theEvent

    Parameters

    theEvent

    An object encapsulating information about the mouse-down event.

    Discussion

    The default implementation calls menuForEvent: and, if non nil, presents the contextual menu. In OS X v10.7 and later, if the event is not handled, this method passes it up the responder chain.

    Availability

    Available in OS X v10.0 and later.

    See Also

    rightMouseDown: (NSResponder)

  • A Boolean value indicating whether the view can pass mouse down events through to its superviews. (read-only)

    Declaration

    Swift

    var mouseDownCanMoveWindow: Bool { get }

    Objective-C

    @property(readonly) BOOL mouseDownCanMoveWindow

    Discussion

    This property lets you create iApp-style apps where you determine the region by which a window can be moved. The default value of this property is NOfalse if the view is opaque; otherwise, it is set to YEStrue. Subclasses can override this property to return different values based on the event.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • The text input context object for the receiver. (read-only)

    Declaration

    Swift

    var inputContext: NSTextInputContext? { get }

    Objective-C

    @property(readonly, strong) NSTextInputContext *inputContext

    Discussion

    The value of this property is nil when the view does not conform to the NSTextInputClient protocol.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • A Boolean value indicating whether the view accepts touch events.

    Declaration

    Swift

    var acceptsTouchEvents: Bool

    Objective-C

    @property BOOL acceptsTouchEvents

    Discussion

    A view accepts touch events when the value of this property is YEStrue. By default, views do not accept touch events, so the default value of this property is NOfalse. You can override this property and return a different value if you want your view to handle touch events.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • A Boolean value indicating whether the view wants resting touches.

    Declaration

    Swift

    var wantsRestingTouches: Bool

    Objective-C

    @property BOOL wantsRestingTouches

    Discussion

    A resting touch occurs when a user rests their thumb on a device (for example, the glass trackpad of a MacBook). By default, these touches are not delivered and are not included in the event's set of touches. Touches may transition in and out of resting at any time. Unless the view wants resting touches, began / ended events are simulated as touches transition from resting to active and vice versa.

    The default value of this property is NOfalse, which indicates that the view does not want resting touches.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • A Boolean value indicating whether the receiver can become key view. (read-only)

    Declaration

    Swift

    var canBecomeKeyView: Bool { get }

    Objective-C

    @property(readonly) BOOL canBecomeKeyView

    Discussion

    When the value of this property is YEStrue, the view can become the key view. In order to become the key view, the view must be visible, it must be installed in a window that supports keyboard entry, and the view’s acceptsFirstResponder method must return YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value indicating whether the view needs its panel to become the key window before it can handle keyboard input and navigation.

    Declaration

    Swift

    var needsPanelToBecomeKey: Bool { get }

    Objective-C

    @property(readonly) BOOL needsPanelToBecomeKey

    Discussion

    The default value of this property is NOfalse. Subclasses can override this property and use their implementation to determine if the view requires its panel to become the key window so that it can handle keyboard input and navigation. Such a subclass should also override acceptsFirstResponder to return YEStrue.

    This property is also used in keyboard navigation. It determines if a mouse click should give focus to a view—that is, make it the first responder). Some views (for example, text fields) want to receive the keyboard focus when you click in them. Other views (for example, buttons) receive focus only when you tab to them. You wouldn't want focus to shift from a textfield that has editing in progress simply because you clicked on a check box.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    becomesKeyOnlyIfNeeded (NSPanel)

  • The view object that follows the current view in the key view loop.

    Declaration

    Swift

    unowned(unsafe) var nextKeyView: NSView?

    Objective-C

    @property(assign) NSView *nextKeyView

    Discussion

    The value in this property is nil if there is no next view in the key view loop. You can assign a view to this property to make that view the next view in the loop. The view in this property should, if possible, be made first responder when the user navigates forward from the receiver using keyboard interface control.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The closest view object in the key view loop that follows the current view in the key view loop and accepts first responder status. (read-only)

    Declaration

    Swift

    unowned(unsafe) var nextValidKeyView: NSView? { get }

    Objective-C

    @property(readonly, assign) NSView *nextValidKeyView

    Return Value

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

    Discussion

    The value in this property is nil if there is no view that follows the current view and accepts the first responder status. AppKit ignores hidden views when it determines the next valid key view.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The view object preceding the current view in the key view loop. (read-only)

    Declaration

    Swift

    unowned(unsafe) var previousKeyView: NSView? { get }

    Objective-C

    @property(readonly, assign) NSView *previousKeyView

    Discussion

    The value in this property is nil if there is no view preceding the current view in the key view loop. The view in this property should, if possible, be made first responder when the user navigates backward from the current view using keyboard interface control.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The closest view object in the key view loop that precedes the current view and accepts first responder status. (read-only)

    Declaration

    Swift

    unowned(unsafe) var previousValidKeyView: NSView? { get }

    Objective-C

    @property(readonly, assign) NSView *previousValidKeyView

    Discussion

    The value in this property is nil if there is no view that precedes the current view and accepts the first responder status. AppKit ignores hidden views when it determines the previous valid key view.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value indicating whether the view supports responsive scrolling.

    Declaration

    Swift

    class func isCompatibleWithResponsiveScrolling() -> Bool

    Objective-C

    + (BOOL)isCompatibleWithResponsiveScrolling

    Return Value

    YEStrue if the view supports responsive scrolling or NOfalse if it does not.

    Discussion

    The default implementation of this method returns YEStrue unless the class overrides the lockFocus or scrollWheel: method. Subclasses such as NSScrollView and NSClipView override this method and perform additional checks.

    AppKit enables responsive scrolling when the views involved in scrolling—the NSScrollView, NSClipView, and embedded document view—all return YEStrue from this method. You can override this method in your custom views and return an appropriate value to reflect your view’s support for the feature.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

  • Prepares the overdraw region for drawing.

    Declaration

    Swift

    func prepareContentInRect(_ rect: NSRect)

    Objective-C

    - (void)prepareContentInRect:(NSRect)rect

    Parameters

    rect

    The current overdraw region, specified in the view’s coordinate system. This rectangle includes the view’s visible rectangle plus any space surrounding the visible rectangle that represents the overdraw region.

    Discussion

    During responsive scrolling, AppKit calls this method before asking your view to draw any content in the overdraw region. You can override this method in your own views and use it to prepare the content that is about to be drawn. For example, if your app defers the creation of subviews until they are scrolled into view, you would use this method to create them and add them to your view hierarchy.

    Your implementation of this method must call super at some point. When calling super, you can extend the overdraw rectangle by passing a different rectangle for the rect parameter. For example, if you add a subview whose frame falls outside the current rectangle, you can grow the rectangle to include the entire frame of the subview.

    AppKit may call this method multiple times to build up the current overdraw region slowly. Each time it calls the method, it extends the overdraw rectangle passed in the rect parameter. If you pass the same rectangle to super twice in succession, AppKit stops generating additional overdraw content. You can use this behavior to avoid generating more overdraw content than makes sense for your app. If the user scrolls the content, AppKit resets the current overdraw region and starts asking your app for content again. You can also reset the current overdraw region by assigning a value to the preparedContentRect property.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

  • The portion of the view that has been rendered and is available for responsive scrolling.

    Declaration

    Swift

    var preparedContentRect: NSRect

    Objective-C

    @property NSRect preparedContentRect

    Discussion

    During responsive scrolling, this property specifies the portion of the view that has been rendered and is ready to scroll. This rectangle always includes the visible portion of the view and may also include nonvisible portions that have been rendered and cached.

    Changing the value of this property alerts AppKit that it might need to generate new overdraw content. For example, setting the value to the current visible rectangle forces AppKit to throw away any cached overdraw content and regenerate it during the next idle period. Never assign a rectangle that is smaller than the visible rectangle.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

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

    Declaration

    Swift

    func scrollPoint(_ aPoint: NSPoint)

    Objective-C

    - (void)scrollPoint:(NSPoint)aPoint

    Parameters

    aPoint

    The point in the receiver to scroll to.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func scrollRectToVisible(_ aRect: NSRect) -> Bool

    Objective-C

    - (BOOL)scrollRectToVisible:(NSRect)aRect

    Parameters

    aRect

    The rectangle to be made visible in the clip view.

    Discussion

    YEStrue if any scrolling is performed; otherwise returns NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func autoscroll(_ theEvent: NSEvent) -> Bool

    Objective-C

    - (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 YEStrue if any scrolling is performed; otherwise returns NOfalse.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func adjustScroll(_ proposedVisibleRect: NSRect) -> NSRect

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func scrollRect(_ aRect: NSRect, by offset: NSSize)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The nearest ancestor scroll view that contains the current view. (read-only)

    Declaration

    Swift

    var enclosingScrollView: NSScrollView? { get }

    Objective-C

    @property(readonly, strong) NSScrollView *enclosingScrollView

    Discussion

    If the current view is not embedded inside a scroll view, the value of this property is nil. This property does not contain the current view if the current view is itself a scroll view. It always contains an ancestor scroll view.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func scrollClipView(_ aClipView: NSClipView, toPoint newOrigin: NSPoint)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    scrollToPoint: (NSClipView)

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

    Declaration

    Swift

    func reflectScrolledClipView(_ aClipView: NSClipView)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.