NSClipView Class Objective-C Reference

Inherits from
NSView : NSResponder : NSObject
Conforms to
NSAnimatablePropertyContainer (NSView)
NSUserInterfaceItemIdentification (NSView)
NSDraggingDestination (NSView)
NSCoding (NSResponder)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Cocoa Drawing Guide
Declared in
NSClipView.h
Related sample code

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

Creation

Interface Builder
– initWithFrame:

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

Tasks

Setting the Document View

Scrolling

Determining Scrolling Efficiency

Getting the Visible Portion

Setting the Document Cursor

Working with Background Color

Overriding NSView Methods

Instance Methods

autoscroll:

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

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSClipView.h

backgroundColor

Returns the color of the receiver’s background.

- (NSColor *)backgroundColor
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

constrainScrollPoint:

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

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

copiesOnScroll

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
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

documentCursor

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

- (NSCursor *)documentCursor
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

documentRect

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

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

documentView

Returns the receiver’s document view.

- (id)documentView
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

documentVisibleRect

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

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

drawsBackground

Returns YES if the receiver draws its background color.

- (BOOL)drawsBackground
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

scrollToPoint:

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

- (void)scrollToPoint:(NSPoint)newOrigin
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

setBackgroundColor:

Sets the receiver’s background color to aColor.

- (void)setBackgroundColor:(NSColor *)aColor
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

setCopiesOnScroll:

Controls whether the receiver copies rendered images while scrolling.

- (void)setCopiesOnScroll:(BOOL)flag
Discussion

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.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

setDocumentCursor:

Sets the cursor object used over the receiver to aCursor.

- (void)setDocumentCursor:(NSCursor *)aCursor
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

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.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSClipView.h

setDrawsBackground:

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

- (void)setDrawsBackground:(BOOL)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 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.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSClipView.h

viewBoundsChanged:

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

- (void)viewBoundsChanged:(NSNotification *)aNotification
Availability
  • Available in OS X v10.0 and later.
Declared In
NSClipView.h

viewFrameChanged:

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

- (void)viewFrameChanged:(NSNotification *)aNotification
Availability
  • Available in OS X v10.0 and later.
Declared In
NSClipView.h


© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-05-23)

Did this document help you? Yes It's good, but... Not helpful...