---

NSScrollView

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

• Configurable scrollers

• Configurable rulers

• Small and large increment scrolling

• Dynamic (continuous) scrolling

• Display of a special cursor over its document view

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

Constructors

• NSScrollView

Calculating Layout

• contentSizeForFrameSize
• frameSizeForContentSize

Determining Component Sizes

• contentSize
• documentVisibleRect

Managing Graphics Attributes

• setBackgroundColor
• backgroundColor
• drawsBackground
• setDrawsBackground
• setBorderType
• borderType
• setDocumentCursor
• documentCursor

Managing the Scrolled Views

• setContentView
• contentView
• setDocumentView
• documentView

Managing Scrollers

• setHorizontalScroller
• horizontalScroller
• setHasHorizontalScroller
• hasHorizontalScroller
• setVerticalScroller
• verticalScroller
• setHasVerticalScroller
• hasVerticalScroller
• setAutohidesScrollers
• autohidesScrollers

Managing Rulers

• setRulerViewClass
• rulerViewClass
• setHasHorizontalRuler
• hasHorizontalRuler
• setHorizontalRulerView
• horizontalRulerView
• setHasVerticalRuler
• hasVerticalRuler
• setVerticalRulerView
• verticalRulerView
• setRulersVisible
• rulersVisible

Setting Scrolling Behavior

• setLineScroll
• lineScroll
• setHorizontalLineScroll
• horizontalLineScroll
• setVerticalLineScroll
• verticalLineScroll
• setPageScroll
• pageScroll
• setHorizontalPageScroll
• horizontalPageScroll
• setVerticalPageScroll
• verticalPageScroll
• setScrollsDynamically
• scrollsDynamically
• scrollWheel

Updating Display After Scrolling

• reflectScrolledClipView

Arranging Components

• tile

Static Methods

contentSizeForFrameSize

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

public static NSSize contentSizeForFrameSize(NSSize frameSize, boolean hFlag, boolean vFlag, int borderType)

Discussion

hFlag and vFlag indicate whether a horizontal or vertical scroller, respectively, is present. If either flag is true 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.

See Also

• frameSizeForContentSize
• scrollerWidth (NSScroller)

frameSizeForContentSize

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

public static NSSize frameSizeForContentSize(NSSize contentSize, boolean hFlag, boolean vFlag, int borderType)

Discussion

The hFlag and vFlag arguments indicate whether a horizontal or vertical scroller, respectively, is present. If either flag is true 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.

See Also

• contentSizeForFrameSize
• scrollerWidth (NSScroller)

rulerViewClass

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

public static Class rulerViewClass()

Discussion

This class is normally NSRulerView.

See Also

• setRulerViewClass

setRulerViewClass

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

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

See Also

• rulerViewClass

Instance Methods

autohidesScrollers

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

public boolean autohidesScrollers()

Availability

• Available in Mac OS X v10.3 and later.

See Also

• setAutohidesScrollers

backgroundColor

Returns the content view’s background color.

public NSColor backgroundColor()

See Also

• setBackgroundColor
• backgroundColor (NSClipView)

borderType

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

public int borderType()

contentSize

Returns the size of the receiver’s content view.

public NSSize contentSize()

See Also

• contentSizeForFrameSize

contentView

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

public NSClipView contentView()

See Also

• setContentView
• documentView

documentCursor

Returns the content view’s document cursor.

public NSCursor documentCursor()

See Also

• setDocumentCursor
• documentCursor (NSClipView)

documentView

Returns the view the receiver scrolls within its content view.

public NSView documentView()

See Also

• setDocumentView
• documentView (NSClipView)

documentVisibleRect

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

public NSRect documentVisibleRect()

See Also

• documentVisibleRect (NSClipView)
• visibleRect (NSView)

drawsBackground

Returns true if the receiver cell fills the background with its background color; otherwise, false.

public boolean drawsBackground()

hasHorizontalRuler

Returns true if the receiver maintains a horizontal ruler view, false if it doesn’t.

public boolean hasHorizontalRuler()

Discussion

Display of rulers is controlled using the setRulersVisible method.

See Also

• horizontalRulerView
• setHasHorizontalRuler
• hasVerticalRuler
• rulerViewClass

hasHorizontalScroller

Returns true if the receiver displays a horizontal scroller, false if it doesn’t.

public boolean hasHorizontalScroller()

See Also

• horizontalScroller
• setHasHorizontalScroller
• hasVerticalScroller

hasVerticalRuler

Returns true if the receiver maintains a vertical ruler view, false if it doesn’t.

public boolean hasVerticalRuler()

Discussion

Display of rulers is controlled using the setRulersVisible method.

See Also

• verticalRulerView
• setHasVerticalRuler
• hasHorizontalRuler
• rulerViewClass

hasVerticalScroller

Returns true if the receiver displays a vertical scroller, false if it doesn’t.

public boolean hasVerticalScroller()

See Also

• verticalScroller
• setHasVerticalScroller
• hasHorizontalScroller

horizontalLineScroll

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

public float horizontalLineScroll()

Discussion

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

See Also

• setHorizontalLineScroll
• verticalLineScroll
• setLineScroll
• horizontalPageScroll

horizontalPageScroll

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

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

See Also

• setHorizontalPageScroll
• verticalPageScroll
• setPageScroll
• horizontalLineScroll

horizontalRulerView

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

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

See Also

• hasHorizontalRuler
• verticalRulerView

horizontalScroller

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

public NSScroller horizontalScroller()

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.

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

See Also

• setLineScroll
• verticalPageScroll
• horizontalPageScroll

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.

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

See Also

• setPageScroll
• verticalLineScroll
• horizontalLineScroll

reflectScrolledClipView

public void reflectScrolledClipView(NSClipView aClipView)

Discussion

If aClipView is the receiver’s content view, adjusts the receiver’s scrollers to reflect the size and positioning of its document view. Does nothing if aClipView is any other view object (in particular, if it’s an NSClipView that isn’t the content view).

This method is invoked automatically during scrolling and when an NSClipView’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.

See Also

• contentView
• documentView

rulersVisible

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

public boolean rulersVisible()

See Also

• hasHorizontalRuler
• hasVerticalRuler

scrollsDynamically

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

public boolean scrollsDynamically()

Discussion

NSScrollView scrolls dynamically by default.

See Also

• setScrollsDynamically

scrollWheel

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

public void scrollWheel(NSEvent theEvent)

setAutohidesScrollers

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

public void setAutohidesScrollers(boolean 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

• Available in Mac OS X v10.3 and later.

See Also

• autohidesScrollers

setBackgroundColor

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

public void setBackgroundColor(NSColor aColor)

Discussion

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

See Also

• backgroundColor
• setBackgroundColor (NSClipView)

setBorderType

Sets the border type of the receiver to borderType.

public void setBorderType(int borderType)

Discussion

borderType may be one of:

• NSView.NoBorder

• NSView.LineBorder

• NSView.BezelBorder

• NSView.GrooveBorder

See Also

• borderType

setContentView

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

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

See Also

• contentView
• setDocumentView

setDocumentCursor

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

public void setDocumentCursor(NSCursor aCursor)

See Also

• documentCursor

setDocumentView

Sets the receiver’s document view to aView.

public void setDocumentView(NSView aView)

See Also

• documentView
• setDocumentView (NSClipView)

setDrawsBackground

Sets whether the receiver draws its background.

public void setDrawsBackground(boolean flag)

Discussion

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

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

See Also

• drawsBackground
• copiesOnScroll (NSClipView)
• setDrawsBackground (NSClipView)

setHasHorizontalRuler

Determines whether the receiver keeps a horizontal ruler object.

public void setHasHorizontalRuler(boolean flag)

Discussion

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

See Also

• hasHorizontalRuler
• horizontalRulerView
• setHasVerticalRuler

setHasHorizontalScroller

Determines whether the receiver keeps a horizontal scroller.

public void setHasHorizontalScroller(boolean flag)

Discussion

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

See Also

• hasHorizontalScroller
• horizontalScroller
• setHasVerticalScroller

setHasVerticalRuler

Determines whether the receiver keeps a vertical ruler object.

public void setHasVerticalRuler(boolean flag)

Discussion

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

See Also

• hasVerticalRuler
• verticalRulerView
• setHasHorizontalRuler
• setRulersVisible

setHasVerticalScroller

Determines whether the receiver keeps a vertical scroller.

public void setHasVerticalScroller(boolean flag)

Discussion

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

See Also

• hasVerticalScroller
• verticalScroller
• setHasHorizontalScroller

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.

public void setHorizontalLineScroll(float 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.

See Also

• lineScroll
• setPageScroll

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.

public void setHorizontalPageScroll(float 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.

See Also

• pageScroll
• setLineScroll

setHorizontalRulerView

Sets the receiver’s horizontal ruler view to aRulerView.

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

See Also

• horizontalRulerView
• setHasHorizontalRuler
• setVerticalRulerView
• setRulersVisible

setHorizontalScroller

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

public void setHorizontalScroller(NSScroller aScroller)

Discussion

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

See Also

• horizontalScroller
• setVerticalScroller

setLineScroll

Sets the horizontal and vertical line scroll amounts to aFloat.

public void setLineScroll(float 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.

See Also

• verticalLineScroll
• horizontalLineScroll

setPageScroll

Sets the horizontal and vertical page scroll amounts to aFloat.

public void setPageScroll(float 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.

See Also

• verticalPageScroll
• verticalLineScroll

setRulersVisible

Determines whether the receiver displays its rulers.

public void setRulersVisible(boolean flag)

Discussion

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

See Also

• rulersVisible
• hasHorizontalRuler
• hasVerticalRuler

setScrollsDynamically

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

public void setScrollsDynamically(boolean flag)

Discussion

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

See Also

• scrollsDynamically

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.

public void setVerticalLineScroll(float 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.

See Also

• verticalLineScroll
• setHorizontalLineScroll
• lineScroll
• setVerticalPageScroll

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.

public void setVerticalPageScroll(float 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.

See Also

• verticalPageScroll
• setHorizontalPageScroll
• pageScroll
• setVerticalLineScroll

setVerticalRulerView

Sets the receiver’s vertical ruler view to aRulerView.

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

See Also

• verticalRulerView
• setHasVerticalRuler
• setHorizontalRulerView
• setRulersVisible

setVerticalScroller

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

public void setVerticalScroller(NSScroller aScroller)

Discussion

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

See Also

• verticalScroller
• setHorizontalScroller

tile

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

public void tile()

Discussion

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

verticalLineScroll

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

public float verticalLineScroll()

Discussion

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

See Also

• setVerticalLineScroll
• horizontalLineScroll
• setLineScroll
• verticalPageScroll

verticalPageScroll

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

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

See Also

• setVerticalPageScroll
• horizontalPageScroll
• setPageScroll
• verticalLineScroll

verticalRulerView

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

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

See Also

• hasVerticalRuler
• horizontalRulerView

verticalScroller

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

public NSScroller verticalScroller()

See Also

• hasVerticalScroller
• setVerticalScroller
• horizontalScroller

---