Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/AppKit.framework |
Availability | Available in Mac OS X v10.0 and later. |
Companion guide | |
Declared in | NSClipView.h |
Related sample code |
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.
Efficient scrolling by copying drawn portions of the document view
Monitoring of document view for automatic update
– initWithFrame:
Initializes the NSClipView.
setDocumentView:
Sets the view scrolled within the NSClipView.
setCopiesOnScroll:
Sets whether the NSClipView copies drawn portions of the document view during scrolling.
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.
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 NO to an NSScrollView has the added effect of sending the NSClipView a setCopiesOnScroll:
message with a parameter of NO. 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.
Scrolls the receiver proportionally to theEvent’s distance outside of it.
- (BOOL)autoscroll:(NSEvent *)theEvent
theEvent’s location should be expressed in the window’s base coordinate system (which it normally is), not the receiving NSClipView’s. Returns YES
if any scrolling is performed; otherwise returns NO
.
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.
NSClipView.h
Returns the color of the receiver’s background.
- (NSColor *)backgroundColor
NSClipView.h
Returns a scroll point adjusted from proposedNewOrigin, if necessary, to guarantee the receiver will still lie within its document view.
- (NSPoint)constrainScrollPoint:(NSPoint)proposedNewOrigin
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.
NSClipView.h
Returns YES
if the receiver copies its existing rendered image while scrolling (only drawing exposed portions of its document view), NO
if it forces its contents to be redrawn each time.
- (BOOL)copiesOnScroll
NSClipView.h
Returns the cursor object used when the cursor lies over the receiver.
- (NSCursor *)documentCursor
NSClipView.h
Returns the rectangle defining the document view’s frame, adjusted to the size of the receiver if the document view is smaller.
- (NSRect)documentRect
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.
– reflectScrolledClipView:
(NSScrollView)– documentVisibleRect
NSClipView.h
Returns the receiver’s document view.
- (id)documentView
NSClipView.h
Returns the exposed rectangle of the receiver’s document view, in the document view’s own coordinate system.
- (NSRect)documentVisibleRect
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.
NSClipView.h
Returns YES
if the receiver draws its background color.
- (BOOL)drawsBackground
NSClipView.h
Changes the origin of the receiver’s bounds rectangle to newOrigin.
- (void)scrollToPoint:(NSPoint)newOrigin
NSClipView.h
Sets the receiver’s background color to aColor.
- (void)setBackgroundColor:(NSColor *)aColor
NSClipView.h
Controls whether the receiver copies rendered images while scrolling.
- (void)setCopiesOnScroll:(BOOL)flag
If flag is YES
, 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 NO
, the receiver always forces its document view to draw itself on scrolling.
NSClipView.h
Sets the cursor object used over the receiver to aCursor.
- (void)setDocumentCursor:(NSCursor *)aCursor
NSClipView.h
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.
- (void)setDocumentView:(NSView *)aView
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 NSViewFrameDidChangeNotification
and NSViewBoundsDidChangeNotification
, adjusts the key view loop to include the new document view, and updates a parent NSScrollView’s display if needed using reflectScrolledClipView:
.
NSClipView.h
Sets whether the receiver draws its background color, depending on the Boolean value flag.
- (void)setDrawsBackground:(BOOL)flag
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 NO to an NSScrollView has the added effect of sending the NSClipView a setCopiesOnScroll:
message with a parameter of NO. 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.
NSClipView.h
Handles an NSViewBoundsDidChangeNotification
, passed in the aNotification argument, by updating a containing NSScrollView based on the new bounds.
- (void)viewBoundsChanged:(NSNotification *)aNotification
NSClipView.h
Handles an NSViewFrameDidChangeNotification
, passed in the aNotification argument, by updating a containing NSScrollView based on the new frame.
- (void)viewFrameChanged:(NSNotification *)aNotification
NSClipView.h
© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-05-23)