ADC Home > Reference Library > Reference > Cocoa > Graphics & Imaging > NSScrollView Class Reference >

Next Page > Hide TOC

NSScrollView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSScrollView.h
Related sample code

Class at a Glance

An NSScrollView allows the user to scroll a document view that’s too large to display in its entirety. In addition to the document view, it displays horizontal and vertical scrollers and rulers (depending on which it’s configured to have).

Principal Attributes

Creation

Interface Builder

Drag a scroll view to a window.

Commonly Used Methods

setDocumentView:

Sets the scroll view’s document view.

setLineScroll:

Sets the amount by which the document view moves during scrolling.

setRulersVisible:

Displays or hides rulers.

Overview

The NSScrollView class is the central coordinator for the Application Kit’s scrolling machinery, composed of this class, NSClipView, and NSScroller. An NSScrollView displays a portion of a document view that’s too large to be displayed whole and provides NSScroller scroll bars that allow the user to move the document view within the NSScrollView. Note that, 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.

Tasks

Calculating Layout

Determining Component Sizes

Managing Graphics Attributes

Managing the Scrolled Views

Managing Scrollers

Managing Rulers

Setting Scrolling Behavior

Updating Display After Scrolling

Arranging Components

Class Methods

contentSizeForFrameSize:hasHorizontalScroller:hasVerticalScroller:borderType:

Returns the size of a content view for an NSScrollView whose frame size is frameSize.

+ (NSSize)contentSizeForFrameSize:(NSSize)frameSize hasHorizontalScroller:(BOOL)hFlag hasVerticalScroller:(BOOL)vFlag borderType:(NSBorderType)borderType

Discussion

hFlag and vFlag indicate whether a horizontal or vertical scroller, respectively, is present. If either flag is YES then the content size is reduced in the appropriate dimension by the width of an NSScroller. The borderType argument indicates the appearance of the NSScrollView’s edge, which also affects the content size; see the description of setBorderType: for a list of possible values.

For an existing NSScrollView, you can simply use the contentSize method.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

frameSizeForContentSize:hasHorizontalScroller:hasVerticalScroller:borderType:

Returns the frame size of an NSScrollView that contains a content view whose size is contentSize.

+ (NSSize)frameSizeForContentSize:(NSSize)contentSize hasHorizontalScroller:(BOOL)hFlag hasVerticalScroller:(BOOL)vFlag borderType:(NSBorderType)borderType

Discussion

The hFlag and vFlag arguments indicate whether a horizontal or vertical scroller, respectively, is present. If either flag is YES then the frame size is increased in the appropriate dimension by the width of an NSScroller. borderType indicates the appearance of the NSScrollView’s edge, which also affects the frame size; see the description of setBorderType: for a list of possible values.

For an existing NSScrollView, you can simply use the frame method and extract its size.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

rulerViewClass

Returns the default class to be used for ruler objects in NSScrollViews.

+ (Class)rulerViewClass

Discussion

This class is normally NSRulerView.

Availability
See Also
Declared In
NSScrollView.h

setRulerViewClass:

Sets the default class to be used for ruler objects in NSScrollViews to aClass.

+ (void)setRulerViewClass:(Class)aClass

Discussion

This class is normally NSRulerView, but you can use this method to set it to a custom subclass of NSRulerView.

This method simply sets a global variable private to NSScrollView. Subclasses of NSScrollView should override both this method and rulerViewClass to store their ruler view classes in private variables.

Availability
See Also
Declared In
NSScrollView.h

Instance Methods

autohidesScrollers

Returns YES when autohiding is set for scroll bars in the receiver.

- (BOOL)autohidesScrollers

Availability
See Also
Declared In
NSScrollView.h

backgroundColor

Returns the content view’s background color.

- (NSColor *)backgroundColor

Availability
See Also
Declared In
NSScrollView.h

borderType

Returns a value that represents the type of border surrounding the receiver; see the description of setBorderType: for a list of possible values.

- (NSBorderType)borderType

Availability
Declared In
NSScrollView.h

contentSize

Returns the size of the receiver’s content view.

- (NSSize)contentSize

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

contentView

Returns the receiver’s content view, the view that clips the document view.

- (NSClipView *)contentView

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

documentCursor

Returns the content view’s document cursor.

- (NSCursor *)documentCursor

Availability
See Also
Declared In
NSScrollView.h

documentView

Returns the view the receiver scrolls within its content view.

- (id)documentView

Availability
See Also
Declared In
NSScrollView.h

documentVisibleRect

Returns the portion of the document view, in its own coordinate system, visible through the receiver’s content view.

- (NSRect)documentVisibleRect

Availability
See Also
Declared In
NSScrollView.h

drawsBackground

Returns YES if the receiver cell fills the background with its background color; otherwise, NO.

- (BOOL)drawsBackground

Availability
Declared In
NSScrollView.h

hasHorizontalRuler

Returns YES if the receiver maintains a horizontal ruler view, NO if it doesn’t.

- (BOOL)hasHorizontalRuler

Discussion

Display of rulers is controlled using the setRulersVisible: method.

Availability
See Also
Declared In
NSScrollView.h

hasHorizontalScroller

Returns YES if the receiver displays a horizontal scroller, NO if it doesn’t.

- (BOOL)hasHorizontalScroller

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

hasVerticalRuler

Returns YES if the receiver maintains a vertical ruler view, NO if it doesn’t.

- (BOOL)hasVerticalRuler

Discussion

Display of rulers is controlled using the setRulersVisible: method.

Availability
See Also
Declared In
NSScrollView.h

hasVerticalScroller

Returns YES if the receiver displays a vertical scroller, NO if it doesn’t.

- (BOOL)hasVerticalScroller

Availability
See Also
Declared In
NSScrollView.h

horizontalLineScroll

Returns the amount by which the receiver scrolls itself horizontally when scrolling line by line, expressed in the content view’s coordinate system.

- (CGFloat)horizontalLineScroll

Discussion

This amount is used when the user clicks the scroll arrows on the horizontal scroll bar without holding down a modifier key.

Availability
See Also
Declared In
NSScrollView.h

horizontalPageScroll

Returns the amount of the document view kept visible when scrolling horizontally page by page, expressed in the content view’s coordinate system.

- (CGFloat)horizontalPageScroll

Discussion

This amount is used when the user clicks the scroll arrows on the horizontal scroll bar while holding down the Option key.

This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page.

Availability
See Also
Declared In
NSScrollView.h

horizontalRulerView

Returns the receiver’s horizontal ruler view, regardless of whether the receiver is currently displaying it, or nil if the receiver has none.

- (NSRulerView *)horizontalRulerView

Discussion

If the receiver is set to display a horizontal ruler view and doesn’t yet have one, this method creates an instance of the ruler view class set using the class method setRulerViewClass:. Display of rulers is controlled using the setRulersVisible: method.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

horizontalScroller

Returns the receiver’s horizontal scroller, regardless of whether the receiver is currently displaying it, or nil if the receiver has none.

- (NSScroller *)horizontalScroller

Availability
Declared In
NSScrollView.h

lineScroll

Returns the vertical line scroll amount: the amount by which the receiver scrolls itself vertically when scrolling line by line, expressed in the content view’s coordinate system.

- (CGFloat)lineScroll

Discussion

This amount is used when the user clicks the scroll arrows on the vertical scroll bar without holding down a modifier key. As part of its implementation, this method calls verticalLineScroll.

Note that a scroll view can have two different line scroll amounts: verticalLineScroll and horizontalLineScroll. Use this method only if you can be sure they’re both the same; for example, you always use setLineScroll:, which sets both amounts to the same value.

Availability
See Also
Declared In
NSScrollView.h

pageScroll

Returns the vertical page scroll amount: the amount of the document view kept visible when scrolling vertically page by page, expressed in the content view’s coordinate system.

- (CGFloat)pageScroll

Discussion

This amount is used when the user clicks the scroll arrows on the vertical scroll bar while holding down the Option key. As part of its implementation, this method calls verticalPageScroll.

This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page.

Note that a scroll view can have two different page scroll amounts: verticalPageScroll and horizontalPageScroll. Use this method only if you can be sure they’re both the same; for example, you always use setPageScroll:, which sets both amounts to the same value.

Availability
See Also
Declared In
NSScrollView.h

reflectScrolledClipView:

Adjusts the receiver’s scrollers to reflect the size and positioning of its content view.

- (void)reflectScrolledClipView:(NSClipView *)aClipView

Parameters
aClipView

The clip view being adjusted to. If aClipView is any view object other than the receiver’s content view, the method does nothing.

Discussion

This method is invoked automatically during scrolling and when an NSClipView object’s relationship to its document view changes; you should rarely need to invoke it yourself, but may wish to override it for custom updating or other behavior. If you override this method, be sure to call the superclass implementation. If you do not, other controls (such as the current scrollers) may not be updated properly.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

rulersVisible

Returns YES if the receiver was set to show rulers using setRulersVisible: (whether or not it has rulers at all), NO if it was set to hide them.

- (BOOL)rulersVisible

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

scrollsDynamically

Returns YES if the receiver redraws its document view while tracking the knob, NO if it redraws only when the scroller knob is released.

- (BOOL)scrollsDynamically

Discussion

NSScrollView scrolls dynamically by default.

Availability
See Also
Declared In
NSScrollView.h

scrollWheel:

Scrolls the receiver up or down, in response to the user moving the mouse’s scroll wheel specified by theEvent.

- (void)scrollWheel:(NSEvent *)theEvent

Availability
Declared In
NSScrollView.h

setAutohidesScrollers:

Determines whether the receiver automatically hides its scroll bars when they are not needed.

- (void)setAutohidesScrollers:(BOOL)flag

Discussion

The horizontal and vertical scroll bars are hidden independently of each other. When autohiding is on and the content of the receiver doesn't extend beyond the size of the clip view on a given axis, the scroller on that axis is removed to leave more room for the content.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

setBackgroundColor:

Sets the color of the content view’s background to aColor.

- (void)setBackgroundColor:(NSColor *)aColor

Discussion

This color is used to paint areas inside the content view that aren’t covered by the document view.

Availability
See Also
Declared In
NSScrollView.h

setBorderType:

Sets the border type of the receiver to borderType.

- (void)setBorderType:(NSBorderType)borderType

Discussion

borderType may be one of:

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

setContentView:

Sets the receiver’s content view, the view that clips the document view, to aView.

- (void)setContentView:(NSClipView *)aView

Discussion

If aView has a document view, this method also sets the receiver’s document view to be the document view of aView. The original content view retains its document view.

Availability
See Also
Declared In
NSScrollView.h

setDocumentCursor:

Sets the cursor used when the cursor is over the content view to aCursor, by sending setDocumentCursor: to the content view.

- (void)setDocumentCursor:(NSCursor *)aCursor

Availability
See Also
Declared In
NSScrollView.h

setDocumentView:

Sets the receiver’s document view to aView.

- (void)setDocumentView:(NSView *)aView

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

setDrawsBackground:

Sets whether the receiver draws its background.

- (void)setDrawsBackground:(BOOL)flag

Discussion

If flag is NO, copy-on-scroll is automatically disabled.

If your NSScrollView encloses an NSClipView sending a setDrawsBackground: message with a parameter of NO to the 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 instead would be the appearance of “trails” (vestiges of previous drawing) in the document view as it is scrolled.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

setHasHorizontalRuler:

Determines whether the receiver keeps a horizontal ruler object.

- (void)setHasHorizontalRuler:(BOOL)flag

Discussion

If flag is YES, the receiver allocates a horizontal ruler the first time it’s needed. Display of rulers is handled independently with the setRulersVisible: method.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

setHasHorizontalScroller:

Determines whether the receiver keeps a horizontal scroller.

- (void)setHasHorizontalScroller:(BOOL)flag

Discussion

If flag is YES, the receiver allocates and displays a horizontal scroller as needed. An NSScrollView by default has neither a horizontal nor a vertical scroller.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

setHasVerticalRuler:

Determines whether the receiver keeps a vertical ruler object.

- (void)setHasVerticalRuler:(BOOL)flag

Discussion

If flag is YES, the receiver allocates a vertical ruler the first time it’s needed. Display of rulers is handled independently with the setRulersVisible: method.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

setHasVerticalScroller:

Determines whether the receiver keeps a vertical scroller.

- (void)setHasVerticalScroller:(BOOL)flag

Discussion

If flag is YES, the receiver allocates and displays a vertical scroller as needed. An NSScrollView by default has neither a vertical nor a horizontal scroller.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

setHorizontalLineScroll:

Sets the amount by which the receiver scrolls itself horizontally when scrolling line by line to aFloat, expressed in the content view’s coordinate system.

- (void)setHorizontalLineScroll:(CGFloat)aFloat

Discussion

This amount is the amount used when the user clicks the scroll arrows on the horizontal scroll bar without holding down a modifier key. When displaying text in an NSScrollView, for example, you might set this amount to the height of a single line of text in the default font.

Availability
See Also
Declared In
NSScrollView.h

setHorizontalPageScroll:

Sets the amount of the document view kept visible when scrolling horizontally page by page to aFloat, expressed in the content view’s coordinate system.

- (void)setHorizontalPageScroll:(CGFloat)aFloat

Discussion

This amount is used when the user clicks the scroll arrows on the horizontal scroll bar while holding down the Option key.

This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page. Thus, setting the page scroll amount to 0.0 implies that the entire visible portion of the document view is replaced when a page scroll occurs.

Availability
See Also
Declared In
NSScrollView.h

setHorizontalRulerView:

Sets the receiver’s horizontal ruler view to aRulerView.

- (void)setHorizontalRulerView:(NSRulerView *)aRulerView

Discussion

You can use this method to override the default ruler class set using the class method setRulerViewClass:. Display of rulers is controlled using the setRulersVisible: method.

Availability
See Also
Declared In
NSScrollView.h

setHorizontalScroller:

Sets the receiver’s horizontal scroller to aScroller, establishing the appropriate target-action relationships between them.

- (void)setHorizontalScroller:(NSScroller *)aScroller

Discussion

To make sure the scroller is visible, invoke the setHasHorizontalScroller: method with an argument of YES.

Availability
See Also
Declared In
NSScrollView.h

setLineScroll:

Sets the horizontal and vertical line scroll amounts to aFloat.

- (void)setLineScroll:(CGFloat)aFloat

Discussion

The line scroll is the amount by which the receiver scrolls itself when scrolling line by line, expressed in the content view’s coordinate system. It’s used when the user clicks the scroll arrows without holding down a modifier key. When displaying text in an NSScrollView, for example, you might set this value to the height of a single line of text in the default font.

As part of its implementation, this method calls setVerticalLineScroll: and setHorizontalLineScroll:.

Availability
See Also
Declared In
NSScrollView.h

setPageScroll:

Sets the horizontal and vertical page scroll amounts to aFloat.

- (void)setPageScroll:(CGFloat)aFloat

Discussion

The page scroll is the amount of the document view kept visible when scrolling page by page to aFloat, expressed in the content view’s coordinate system. It’s used when the user clicks the scroll arrows while holding down the Option key.

This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page. Thus, setting the page scroll amount to 0.0 implies that the entire visible portion of the document view is replaced when a page scroll occurs.

As part of its implementation, this method calls setVerticalPageScroll: and setHorizontalPageScroll:.

Availability
See Also
Declared In
NSScrollView.h

setRulersVisible:

Determines whether the receiver displays its rulers.

- (void)setRulersVisible:(BOOL)flag

Discussion

If flag is YES, the receiver displays its rulers (creating them if needed). If flag is NO, the receiver doesn’t display its rulers.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

setScrollsDynamically:

Determines whether the receiver redraws its document view while scrolling continuously.

- (void)setScrollsDynamically:(BOOL)flag

Discussion

If flag is YES it does; if flag is NO it redraws only when the scroller knob is released. NSScrollView scrolls dynamically by default.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

setVerticalLineScroll:

Sets the amount by which the receiver scrolls itself vertically when scrolling line by line to aFloat, expressed in the content view’s coordinate system.

- (void)setVerticalLineScroll:(CGFloat)aFloat

Discussion

This value is the amount used when the user clicks the scroll arrows on the vertical scroll bar without holding down a modifier key. When displaying text in an NSScrollView, for example, you might set this value to the height of a single line of text in the default font.

Availability
See Also
Declared In
NSScrollView.h

setVerticalPageScroll:

Sets the amount of the document view kept visible when scrolling vertically page by page to aFloat, expressed in the content view’s coordinate system.

- (void)setVerticalPageScroll:(CGFloat)aFloat

Discussion

This amount is used when the user clicks the scroll arrows on the vertical scroll bar while holding down the Option key.

This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page. Thus, setting the page scroll amount to 0.0 implies that the entire visible portion of the document view is replaced when a page scroll occurs.

Availability
See Also
Declared In
NSScrollView.h

setVerticalRulerView:

Sets the receiver’s vertical ruler view to aRulerView.

- (void)setVerticalRulerView:(NSRulerView *)aRulerView

Discussion

You can use this method to override the default ruler class set using the class method setRulerViewClass:. Display of rulers is controlled using the setRulersVisible: method.

Availability
See Also
Declared In
NSScrollView.h

setVerticalScroller:

Sets the receiver’s vertical scroller to aScroller, establishing the appropriate target-action relationships between them.

- (void)setVerticalScroller:(NSScroller *)aScroller

Discussion

To make sure the scroller is visible, invoke the setHasVerticalScroller: method with an argument of YES.

Availability
See Also
Declared In
NSScrollView.h

tile

Lays out the components of the receiver: the content view, the scrollers, and the ruler views.

- (void)tile

Discussion

You rarely need to invoke this method, but subclasses may override it to manage additional components.

Availability
Related Sample Code
Declared In
NSScrollView.h

verticalLineScroll

Returns the amount by which the receiver scrolls itself vertically when scrolling line by line, expressed in the content view’s coordinate system.

- (CGFloat)verticalLineScroll

Discussion

This amount is used when the user clicks the scroll arrows on the vertical scroll bar without holding down a modifier key.

Availability
See Also
Declared In
NSScrollView.h

verticalPageScroll

Returns the amount of the document view kept visible when scrolling vertically page by page, expressed in the content view’s coordinate system.

- (CGFloat)verticalPageScroll

Discussion

This amount is used when the user clicks the scroll arrows on the vertical scroll bar while holding down the Option key.

This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page.

Availability
See Also
Declared In
NSScrollView.h

verticalRulerView

Returns the receiver’s vertical ruler view, regardless of whether the receiver is currently displaying it, or nil if the receiver has none.

- (NSRulerView *)verticalRulerView

Discussion

If the receiver is set to display a vertical ruler view and doesn’t yet have one, this method creates an instance of the ruler view class set using the class method setRulerViewClass:. Display of rulers is controlled using the setRulersVisible: method.

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

verticalScroller

Returns the receiver’s vertical scroller, regardless of whether the receiver is currently displaying it, or nil if the receiver has none.

- (NSScroller *)verticalScroller

Availability
See Also
Related Sample Code
Declared In
NSScrollView.h

Next Page > Hide TOC

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

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.