Mac Developer Library

Developer

AppKit Framework Reference NSClipView Class Reference

Options
Deployment Target:

On This Page
Language:

NSClipView

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

Class at a Glance

An NSClipView contains and scrolls the document view displayed by an NSScrollView. You normally don’t need to program with NSClipView objects, as NSScrollView handles most of the details of their operation.

An NSClipView holds the document view of an NSScrollView, clipping the document view to its frame, handling the details of scrolling in an efficient manner, and updating the NSScrollView when the document view’s size or position changes. You don’t normally use the NSClipView class directly; it’s provided primarily as the scrolling machinery for the NSScrollView class. However, you might use the NSClipView class to implement a class similar to NSScrollView.

Interaction With NSScrollView

When using an NSClipView within an NSScrollView (the usual configuration), you should access the NSScrollView properties that control background drawing state, rather than accessing these properties of the NSClipView. This recommendation applies to the following properties:

The NSClipView methods are intended for when the NSClipView is used independently of a containing NSScrollView. In the usual case, NSScrollView should be allowed to manage the background-drawing properties of its associated NSClipView.

There is only one background-drawing state per NSScrollView/NSClipView pair. The two objects do not maintain independent and distinct drawsBackground and backgroundColor properties; rather, the accessors for these properties on NSScrollView largely defer to the associated NSClipView and allow the NSClipView to maintain the state. Note that this state is not cached by the NSScrollView object.

It is also important to note that setting drawsBackground to NOfalse in an NSScrollView has the added effect of setting the NSClipView property copiesOnScroll to NOfalse. The side effect of setting the drawsBackground property directly to the NSClipView is the appearance of “trails” (vestiges of previous drawing) in the document view as it is scrolled.

  • The clip view’s document view.

    Declaration

    Swift

    unowned(unsafe) var documentView: AnyObject?

    Objective-C

    @property(assign) id documentView

    Discussion

    If the clip view is contained in an NSScrollView, you should send the NSScrollView a setDocumentView: message instead, so it can perform whatever updating it needs. Setting this property to a view removes any previous document view, and sets the origin of the clip view’s bounds rectangle to the origin of the new view’s frame rectangle. Doing so also registers the clip view for the notifications NSViewFrameDidChangeNotification and NSViewBoundsDidChangeNotification, adjusts the key view loop to include the new document view, and updates a parent NSScrollView display if needed using reflectScrolledClipView:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Changes the origin of the clip view’s bounds rectangle to newOrigin.

    Declaration

    Swift

    func scrollToPoint(_ newOrigin: NSPoint)

    Objective-C

    - (void)scrollToPoint:(NSPoint)newOrigin

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Scrolls the clip view proportionally to theEvent’s distance outside of it.

    Declaration

    Swift

    func autoscroll(_ theEvent: NSEvent) -> Bool

    Objective-C

    - (BOOL)autoscroll:(NSEvent *)theEvent

    Discussion

    theEvent’s location should be expressed in the window’s base coordinate system (which it normally is), not the receiving NSClipView. Returns YEStrue if any scrolling is performed; otherwise returns NOfalse.

    Never invoke this method directly; instead, the NSScrollView’s document view should repeatedly send itself autoscroll: messages when the pointer is dragged outside the NSScrollView’s frame during a modal event loop initiated by a mouse-down event. The NSView class implements autoscroll: to forward the message to the receiver’s superview; thus the message is ultimately forwarded to the NSClipView.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a scroll point adjusted from proposedNewOrigin, if necessary, to guarantee the view will still lie within its document view.

    Deprecation Statement

    Use constrainBoundsRect: instead.

    Declaration

    Swift

    func constrainScrollPoint(_ newOrigin: NSPoint) -> NSPoint

    Objective-C

    - (NSPoint)constrainScrollPoint:(NSPoint)newOrigin

    Discussion

    For example, if proposedNewOrigin’s y coordinate lies to the left of the document view’s origin, then the y coordinate returned is set to that of the document view’s origin.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Constrains the bounds of the clip view while the user is magnifying and scrolling.

    Declaration

    Swift

    func constrainBoundsRect(_ proposedBounds: NSRect) -> NSRect

    Objective-C

    - (NSRect)constrainBoundsRect:(NSRect)proposedBounds

    Parameters

    proposedBounds

    The bounds to use to ensure that the view will still lie within its document view.

    Return Value

    A bounds rectangle.

    Discussion

    Note that you can move an implementation of the deprecated constrainScrollPoint: to this method by adjusting the origin of proposedBounds (instead of using the newOrigin parameter in -constrainScrollPoint:). To preserve compatibility, if a subclass overrides -constrainScrollPoint:, the default behavior of constrainBoundsRect: will be to use that -constrainScrollPoint: to adjust the origin of proposedBounds, and to not change the size.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

  • A Boolean value that indicates if the clip view copies rendered images while scrolling.

    Declaration

    Swift

    var copiesOnScroll: Bool

    Objective-C

    @property BOOL copiesOnScroll

    Discussion

    When the value of this property is YEStrue, the clip view copies its existing rendered image while scrolling (only drawing exposed portions of its document view); when it is NOfalse, the view forces its contents to be redrawn each time.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The distance that the content view is inset from the enclosing scroll view.

    Declaration

    Swift

    var contentInsets: NSEdgeInsets

    Objective-C

    @property NSEdgeInsets contentInsets

    Discussion

    When the enclosing scroll view’s contentInsets value is nonzero (that is, the value is not {0,0,0,0}), the scroll view sets the frame of its content view to the scroll view's bounds minus the scroll view’s border, if it has one. (When the contentInsets value is equal to zero, the scroll view adjusts its contentView.frame to fit inside all the other views the scroll view maintains.) When the value of contentView.automaticallyAdjustsContentInsets is YEStrue (which is the default value), the header, rulers, and other views are overlaid on top of the content view and the scroll view sets the correct contentInsets value on the contentView. Note that you can animate the clip view when this property changes by calling [self animator].

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • A Boolean value that indicates if the clip view automatically accounts for other scroll view subviews.

    Declaration

    Swift

    var automaticallyAdjustsContentInsets: Bool

    Objective-C

    @property BOOL automaticallyAdjustsContentInsets

    Discussion

    When the value of this property is YEStrue, and the clip view is used as the contentView of an NSScrollView, the clip view automatically accounts for other scroll view subviews, such as rulers and headers. The default value is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • The rectangle defining the document view’s frame, adjusted to the size of the clip view if the document view is smaller. (read-only)

    Declaration

    Swift

    var documentRect: NSRect { get }

    Objective-C

    @property(readonly) NSRect documentRect

    Discussion

    The document rectangle is used in conjunction with an NSClipView object’s bounds rectangle to determine values for the indicators of relative position and size between the NSClipView and its document view. For example, NSScrollView uses these rectangles to set the size and position of the knobs in its scrollers. When the document view is much larger than the NSClipView, the knob is small; when the document view is near the same size, the knob is large; and when the document view is the same size or smaller, there is no knob.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The exposed rectangle of the clip view’s document view, in the document view’s own coordinate system. (read-only)

    Declaration

    Swift

    var documentVisibleRect: NSRect { get }

    Objective-C

    @property(readonly) NSRect documentVisibleRect

    Discussion

    Note that this rectangle doesn’t reflect the effects of any clipping that may occur above the NSClipView itself. To get the portion of the document view that’s guaranteed to be visible, send it a visibleRect message.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    documentRect

  • The cursor object used when the pointer lies over the view.

    Declaration

    Swift

    var documentCursor: NSCursor?

    Objective-C

    @property(strong) NSCursor *documentCursor

    Discussion

    The default value of this property is nil, unless you specify a value in the xib file associated with the clip view (or scroll view). Note that the clip view’s document view may specify a cursor for its enclosing scroll view by setting enclosingScrollView.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates if the clip view draws its background color.

    Declaration

    Swift

    var drawsBackground: Bool

    Objective-C

    @property BOOL drawsBackground

    Discussion

    If your NSClipView is enclosed in an NSScrollView, you should set the drawsBackground property on the NSScrollView. Setting this property to NOfalse on an NSScrollView has the added effect of setting the NSClipView property copiesOnScroll to NOfalse. The side effect of setting the drawsBackground property on the NSClipView is the appearance of “trails” (vestiges of previous drawing) in the document view as it is scrolled.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The color of the clip view’s background.

    Declaration

    Swift

    @NSCopying var backgroundColor: NSColor

    Objective-C

    @property(copy) NSColor *backgroundColor

    Discussion

    The default value of this property is supplied by the current controlBackgroundColor.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.