---

NSClipView

Class at a Glance

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

Principal Attributes

• Efficient scrolling by copying drawn portions of the document view

• Monitoring of document view for automatic update

Creation

Interface Builder

Constructor

Creates the NSClipView.

Commonly Used Methods

setDocumentView

Sets the view scrolled within the NSClipView.

setCopiesOnScroll

Sets whether the NSClipView copies drawn portions of the document view during scrolling.

Overview

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 issue messages that control background drawing state to the NSScrollView, rather than messaging the NSClipView directly. This recommendation applies to the following methods:

• - setBackgroundColor:

• - backgroundColor

• - setDrawsBackground:

• - drawsBackground

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, NSScrollView's accessors for these properties largely defer to the associated NSClipView and allow the NSClipView to maintain the state. In Mac OS X v10.2 and earlier system versions, NSScrollView maintained a cache of the last state it set for its NSClipView. If the NSClipView was sent a setDrawsBackground: message directly, the cache might not reflect the state accurately. This caching of state has been removed in Mac OS X v10.3.

It is also important to note that sending a setDrawsBackground: message with a parameter of false to an NSScrollView has the added effect of sending the NSClipView a setCopiesOnScroll: message with a parameter of false. The side effect of sending the setDrawsBackground: message directly to the NSClipView is the appearance of “trails” (vestiges of previous drawing) in the document view as it is scrolled.

Tasks

Constructors

• NSClipView

Setting the Document View

• setDocumentView
• documentView

Scrolling

• scrollToPoint
• autoscroll
• constrainScrollPoint

Determining Scrolling Efficiency

• setCopiesOnScroll
• copiesOnScroll

Getting the Visible Portion

• documentRect
• documentVisibleRect

Setting the Document Cursor

• setDocumentCursor
• documentCursor

Working with Background Color

• drawsBackground
• setDrawsBackground
• setBackgroundColor
• backgroundColor

Overriding NSView Methods

• viewBoundsChanged
• viewFrameChanged

Instance Methods

autoscroll

Scrolls the receiver proportionally to theEvent’s distance outside of it.

public boolean 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’s. Returns true if any scrolling is performed; otherwise returns false.

Never invoke this method directly; instead, the NSClipView’s document view should repeatedly send itself autoscroll messages when the cursor is dragged outside the NSClipView’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.

backgroundColor

Returns the color of the receiver’s background.

public NSColor backgroundColor()

See Also

• setBackgroundColor

constrainScrollPoint

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

public NSPoint constrainScrollPoint(NSPoint proposedNewOrigin)

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.

See Also

• scrollToPoint

copiesOnScroll

Returns true if the receiver copies its existing rendered image while scrolling (only drawing exposed portions of its document view), false if it forces its contents to be redrawn each time.

public boolean copiesOnScroll()

See Also

• setCopiesOnScroll

documentCursor

Returns the cursor object used when the cursor lies over the receiver.

public NSCursor documentCursor()

See Also

• setDocumentCursor

documentRect

Returns the rectangle defining the document view’s frame, adjusted to the size of the receiver if the document view is smaller.

public NSRect documentRect()

Discussion

In other words, this rectangle is always at least as large as the receiver itself.

The document rectangle is used in conjunction with an NSClipView’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.

See Also

• reflectScrolledClipView (NSScrollView)
• documentVisibleRect

documentView

Returns the receiver’s document view.

public NSView documentView()

See Also

• setDocumentView

documentVisibleRect

Returns the exposed rectangle of the receiver’s document view, in the document view’s own coordinate system.

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

See Also

• documentRect

drawsBackground

Returns true if the receiver draws its background color.

public boolean drawsBackground()

See Also

• setDrawsBackground

scrollToPoint

Changes the origin of the receiver’s bounds rectangle to newOrigin.

public void scrollToPoint(NSPoint newOrigin)

See Also

• constrainScrollPoint

setBackgroundColor

Sets the receiver’s background color to aColor.

public void setBackgroundColor(NSColor aColor)

See Also

• backgroundColor

setCopiesOnScroll

Controls whether the receiver copies rendered images while scrolling.

public void setCopiesOnScroll(boolean flag)

Discussion

If flag is true, the receiver copies the existing rendered image to its new location while scrolling and only draws exposed portions of its document view. If flag is false, the receiver always forces its document view to draw itself on scrolling.

See Also

• copiesOnScroll

setDocumentCursor

Sets the cursor object used over the receiver to aCursor.

public void setDocumentCursor(NSCursor aCursor)

See Also

• documentCursor

setDocumentView

Sets the receiver’s document view to aView, removing any previous document view, and sets the origin of the receiver’s bounds rectangle to the origin of aView’s frame rectangle.

public void setDocumentView(NSView aView)

Discussion

If the receiver is contained in an NSScrollView, you should send the NSScrollView a setDocumentView message instead, so it can perform whatever updating it needs.

In the process of setting the document view, this method registers the receiver for the notifications ViewFrameDidChangeNotification and ViewBoundsDidChangeNotification, adjusts the key view loop to include the new document view, and updates a parent NSScrollView’s display if needed using reflectScrolledClipView.

See Also

• documentView

setDrawsBackground

Sets whether the receiver draws its background color, depending on the Boolean value flag.

public void setDrawsBackground(boolean flag)

Discussion

If your NSClipView is enclosed in an NSScrollView, you should send the setDrawsBackground: message to the NSScrollView. Sending a setDrawsBackground: message with a parameter of false to an NSScrollView has the added effect of sending the NSClipView a setCopiesOnScroll: message with a parameter of false. The side effect of sending the setDrawsBackground: message directly to the NSClipView is the appearance of “trails” (vestiges of previous drawing) in the document view as it is scrolled.

See Also

• drawsBackground

viewBoundsChanged

Handles a ViewBoundsDidChangeNotification, passed in the aNotification argument, by updating a containing NSScrollView based on the new bounds.

public void viewBoundsChanged(NSNotification aNotification)

viewFrameChanged

Handles a ViewFrameDidChangeNotification, passed in the aNotification argument, by updating a containing NSScrollView based on the new frame.

public void viewFrameChanged(NSNotification aNotification)

---