NSScrollView Class Reference

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

Overview

The NSScrollView class is the central coordinator for the Application Kit’s scrolling machinery, composed of this class, and the NSClipView, and NSScroller classes . A scroll view displays a portion of a document view that’s too large to be displayed whole and provides scroll bars that allow the user to move the document view within the scroll view.

Note that, when using an NSClipView object within an scroll view (the usual configuration), you should issue messages that control background drawing state to the scroll view directly, rather than messaging the clip view.

Tasks

Calculating Layout

Determining Component Sizes

Managing Graphics Attributes

Managing the Views

Managing Scrollers

Managing Rulers

Scroller Style

Setting Scrolling Behavior

Updating Display After Scrolling

Arranging Components

Find Bar Positioning

Specifying a Document’s Predominant Scrolling Behavior

Specifying the Scroll View Elasticity

Flashing Overlay Scroll Bars

Zooming the Scroll View

Properties

allowsMagnification

Allows the user to magnify the scroll view.

@property BOOL allowsMagnification
Discussion

This property does not prevent the developer from manually adjusting the magnification value. If magnification exceeds either the maximum or minimum limits for magnification, and allowsMagnification is YES, the scroll view temporarily animates the content magnification just past those limits before returning to them. The default value is NO.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSScrollView.h

magnification

The amount by which the content is currently scaled.

@property CGFloat magnification
Discussion

To animate the magnification, use the object's animator. The default value is 1.0.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSScrollView.h

maxMagnification

The maximum value to which the content can be magnified.

@property CGFloat maxMagnification
Discussion

This value must be greater than or equal to the minimum magnification. The default value is 4.0.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSScrollView.h

minMagnification

The minimum value to which the content can be magnified.

@property CGFloat minMagnification
Discussion

The default value is 0.25.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSScrollView.h

Class Methods

contentSizeForFrameSize:hasHorizontalScroller:hasVerticalScroller:borderType:

Returns the content size calculated from the frame size and the specified specifications. (Deprecated. Use contentSizeForFrameSize:horizontalScrollerClass:verticalScrollerClass:borderType:controlSize:scrollerStyle: instead.)

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

The frame size in the screen coordinate system

hFlag

A Boolean specifying that a horizontal scroller should be included.

vFlag

A Boolean specifying that a vertical scroller should be included.

borderType

Specifies the appearance of the style of the scroll view’s border. See NSBorderType for a list of possible values.

Return Value

The content view frame size.

Discussion

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

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

contentSizeForFrameSize:horizontalScrollerClass:verticalScrollerClass:borderType:controlSize:scrollerStyle:

Returns the content size calculated from the frame size and the specified specifications.

+ (NSSize)contentSizeForFrameSize:(NSSize)frameSize horizontalScrollerClass:(Class)horizontalScrollerClass verticalScrollerClass:(Class)verticalScrollerClass borderType:(NSBorderType)borderType controlSize:(NSControlSize)controlSize scrollerStyle:(NSScrollerStyle)scrollerStyle
Parameters
frameSize

The frame size in screen coordinates.

horizontalScrollerClass

The class used as the horizontal scroller. A value of nil specifies that no horizontal scroller is used.

verticalScrollerClass

The class used as the vertical scroller. A value of nil specifies that no horizontal scroller is used.

borderType

Specifies the appearance of the style of the scroll view’s border. See NSBorderType for a list of possible values.

controlSize

The control size. The possible values are specified in NSControlSize. NSMiniControlSize is not supported.

scrollerStyle

Specifies the scroll style. See NSScrollerStyle for supported values.

Return Value

The content view frame size.

Discussion

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

Availability
  • Available in OS X v10.7 and later.
Declared In
NSScrollView.h

frameSizeForContentSize:hasHorizontalScroller:hasVerticalScroller:borderType:

Returns the frame size of an scroll view that contains a content view with the specified size. (Deprecated. Use contentSizeForFrameSize:horizontalScrollerClass:verticalScrollerClass:borderType:controlSize:scrollerStyle: instead.)

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

The content size.

hFlag

Specifies if the scroll view has a horizontal scroller.

vFlag

Specifies if the scroll view has a vertical scroller.

borderType

Specifies the appearance of the style of the scroll view’s border. See NSBorderType for a list of possible values.

Return Value

Returns the frame size.

Discussion

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

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

frameSizeForContentSize:horizontalScrollerClass:verticalScrollerClass:borderType:controlSize:scrollerStyle:

Returns the frame size of an scroll view that contains a content view with the specified size.

+ (NSSize)frameSizeForContentSize:(NSSize)contentSize horizontalScrollerClass:(Class)horizontalScrollerClass verticalScrollerClass:(Class)verticalScrollerClass borderType:(NSBorderType)borderType controlSize:(NSControlSize)controlSize scrollerStyle:(NSScrollerStyle)scrollerStyle
Parameters
contentSize

The content size.

horizontalScrollerClass

The class used as the horizontal scroller. A value of nil specifies that no horizontal scroller is used.

verticalScrollerClass

The class used as the vertical scroller. A value of nil specifies that no horizontal scroller is used.

borderType

Specifies the appearance of the style of the scroll view’s border. See NSBorderType for a list of possible values.

controlSize

The control size. The possible values are specified in NSControlSize. NSMiniControlSize is not supported.

scrollerStyle

Specifies the scroll style. See NSScrollerStyle for supported values.

Return Value

The size of the frame for the specified contentSize.

Discussion

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

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

Instance Methods

addFloatingSubview:forAxis:

Adds a floating subview to the document view.

- (void)addFloatingSubview:(NSView *)view forAxis:(NSEventGestureAxis)axis
Parameters
view

The view that can float.

axis

The event gesture axis on which the view can float. A view can float on only one axis at a time.

Discussion

Floating subviews of the document view do not scroll like the rest of the document. Instead these views appear to float over the document. For example, see NSTableView floating group rows (floatsGroupRows).

NSScrollView ensures that any scrolling on the non-floating axis is performed visually synchronously with the document content.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSScrollView.h

autohidesScrollers

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

- (BOOL)autohidesScrollers
Availability
  • Available in OS X v10.3 and later.
Declared In
NSScrollView.h

backgroundColor

Returns the content view’s background color.

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

borderType

Returns a value that represents the type of border surrounding the receiver

- (NSBorderType)borderType
Return Value

Returns the border type. See NSBorderType for a list of possible values.

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

contentSize

Returns the size of the receiver’s content view.

- (NSSize)contentSize
Return Value

Returns the size of the receiver’s content view.

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

contentView

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

- (NSClipView *)contentView
Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSScrollView.h

documentCursor

Returns the content view’s document cursor.

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

documentView

Returns the view the receiver scrolls within its content view.

- (id)documentView
Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
Declared In
NSScrollView.h

findBarPosition

Sets the position of the find bar.

- (NSScrollViewFindBarPosition)findBarPosition
Return Value

The position of the view’s find bar. See “NSScrollViewFindBarPosition” for possible values.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSScrollView.h

flashScrollers

Flash the overlay scroll bars.

- (void)flashScrollers
Discussion

This method is only to scroll views that use overlay scrollers.

This method can be invoked to cause the overlay scroller knobs to be momentarily shown. This may be desirable when changing a document view's size or swapping new content into the view, or to give the user a sense of the current position within the scrollable range at each step of an incremental search or similar operation.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
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
  • Available in OS X v10.0 and later.
Declared In
NSScrollView.h

hasHorizontalScroller

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

- (BOOL)hasHorizontalScroller
Availability
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
Declared In
NSScrollView.h

hasVerticalScroller

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

- (BOOL)hasVerticalScroller
Availability
  • Available in OS X v10.0 and later.
Declared In
NSScrollView.h

horizontalLineScroll

Returns the horizontal line by line scroll amount.

- (CGFloat)horizontalLineScroll
Return Value

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

Discussion

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

Availability
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSScrollView.h

horizontalScrollElasticity

Returns the horizontal scrolling elasticity mode.

- (NSScrollElasticity)horizontalScrollElasticity
Return Value

Returns the horizontal elasticity setting. See “NSScrollElasticity” for the possible values.

Availability
  • Available in OS X v10.7 and later.
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
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSScrollView.h

lineScroll

Returns the vertical line by line scroll amount.

- (CGFloat)lineScroll
Return Value

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.

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

magnifyToFitRect:

Magnifies the content view proportionally such that the given rectangle fits centered in the scroll view.

- (void)magnifyToFitRect:(NSRect)rect
Parameters
rect

The rectangle (in content view space) to which the content view is magnified.

Discussion

The resulting magnification value is clipped to the minMagnification and maxMagnification values. To animate the magnification, use the object's animator.

Availability
  • Available in OS X v10.8 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSScrollView.h

scrollerKnobStyle

Returns the scroll knob style.

- (NSScrollerKnobStyle)scrollerKnobStyle
Return Value

The scroll knob style. See NSScrollerKnobStyle for the supported values.

Discussion

Applicable only to scroll views that use overlay scrollers.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSScrollView.h

scrollerStyle

Returns the scroll view’s scroller style.

- (NSScrollerStyle)scrollerStyle
Return Value

Returns scroller style. See NSScrollerStyle for supported values.

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

setBorderType:

Sets the border type of the receiver to borderType.

- (void)setBorderType:(NSBorderType)borderType
Parameters
borderType

Specifies the appearance of the style of the scroll view’s border. See NSBorderType for a list of possible values.

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

setDocumentView:

Sets the receiver’s document view to aView.

- (void)setDocumentView:(NSView *)aView
Availability
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
See Also
Declared In
NSScrollView.h

setFindBarPosition:

Returns position of the find bar.

- (void)setFindBarPosition:(NSScrollViewFindBarPosition)position
Parameters
position

The position. See “NSScrollViewFindBarPosition” for possible values.

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

setHorizontalScrollElasticity:

Sets the scroll view’s horizontal elasticity mode.

- (void)setHorizontalScrollElasticity:(NSScrollElasticity)elasticity
Parameters
elasticity

The elasticity mode. See “NSScrollElasticity” for the possible values.

Discussion

A scroll view can scroll its contents past its bounds to achieve an elastic effect.

When set to NSScrollElasticityAutomatic, scrolling the horizontal axis beyond its document bounds only occurs if the document width is greater than the view width or, the vertical scroller is hidden and the horizontal scroller is visible.

The default value is NSScrollElasticityAutomatic.

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

setLineScroll:

Sets the horizontal and vertical line scroll amounts to aFloat.

- (void)setLineScroll:(CGFloat)aFloat
Parameters
aFloat

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

Discussion

This value is 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
  • Available in OS X v10.0 and later.
Declared In
NSScrollView.h

setMagnification:centeredAtPoint:

Magnify the content by the given amount and center the result on the given point.

- (void)setMagnification:(CGFloat)magnification centeredAtPoint:(NSPoint)point
Parameters
magnification

The amount by which to magnify the content.

point

The point (in content view space) on which to center magnification.

Discussion

This method scales the content view such that the passed in point (in content view space) remains at the same screen location once the scaling is completed. The resulting magnification value is clipped to the minMagnification and maxMagnification values. To animate the magnification, use the object's animator.

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

setScrollerKnobStyle:

Sets the knob style of scroll views that use the overlay scroller style

- (void)setScrollerKnobStyle:(NSScrollerKnobStyle)newScrollerKnobStyle
Parameters
newScrollerKnobStyle

The scroll knob style. See NSScrollerKnobStyle for the supported values.

Discussion

Applicable only to scroll views that use overlay scrollers.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSScrollView.h

setScrollerStyle:

Determines the scroller style used by the scroll view.

- (void)setScrollerStyle:(NSScrollerStyle)newScrollerStyle
Parameters
newScrollerStyle

The scroller style. See NSScrollerStyle for supported values.

Discussion

This setting is automatically set at runtime, based on the user's preference setting and, if relevant, the set of connected pointing devices and their configured scroll capabilities, as determined by the NSScroller method preferredScrollerStyle.

Setting an scroll view’s scroller style sets the style of both the horizontal and vertical scrollers. If the scroll view subsequently creates or is assigned a new horizontal or vertical scroller, they are assigned the same scroller style assigned to the scroll view.

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

setUsesPredominantAxisScrolling:

Sets whether the scroll view uses a predominant scrolling axis for content.

- (void)setUsesPredominantAxisScrolling:(BOOL)predominantAxisScrolling
Parameters
predominantAxisScrolling

The whether the scroll view supports a predominant scrolling direction. YES if there is a predominant scrolling direction; otherwise NO.

Discussion

Some content is scrollable in both the horizontal and vertical axes, but is predominantly scrolled one axis at a time. Other content (such as a drawing canvas) should scroll freely in both axes.

Traditionally this is not an issue with scroll wheels since they can only scroll in one direction at a time. With scroll balls and touch surfaces, it becomes more difficult to determine the user's intention.

This property helps a scroll view determine the user's intention by specifying if there is a predominant scrolling axis for content.

The default value is YES.

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

setVerticalScrollElasticity:

Sets the scroll view’s vertical elasticity mode.

- (void)setVerticalScrollElasticity:(NSScrollElasticity)elasticity
Parameters
elasticity

The elasticity mode. See “NSScrollElasticity” for the possible values.

Discussion

A scroll view can scroll its contents past its bounds to achieve an elastic effect.

When set to NSScrollElasticityAutomatic, scrolling the vertical axis beyond its document bounds occurs if any of the following are true: the vertical scroller is visible, the content height is greater than view height, or the horizontal scroller hidden.

Availability
  • Available in OS X v10.7 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSScrollView.h

usesPredominantAxisScrolling

Returns whether the scroll view uses a predominant scrolling axis for content.

- (BOOL)usesPredominantAxisScrolling
Return Value

YES if it does; NO otherwise.

Availability
  • Available in OS X v10.7 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSScrollView.h

verticalScrollElasticity

Returns the vertical scrolling elasticity mode.

- (NSScrollElasticity)verticalScrollElasticity
Return Value

Returns the vertical elasticity setting. See “NSScrollElasticity” for the possible values.

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

Constants

NSScrollElasticity

These constants determine the elasticity behavior for an axis of the scrollview.

enum {
   NSScrollElasticityAutomatic = 0,
   NSScrollElasticityNone      = 1,
   NSScrollElasticityAllowed   = 2,
};
typedef NSInteger NSScrollElasticity;
Constants
NSScrollElasticityAutomatic

Automatically determine whether to allow elasticity on this axis.

Available in OS X v10.7 and later.

Declared in NSScrollView.h.

NSScrollElasticityNone

Disallow scrolling beyond document bounds on this axis.

Available in OS X v10.7 and later.

Declared in NSScrollView.h.

NSScrollElasticityAllowed

Allow content to be scrolled past its bounds on this axis in an elastic fashion.

Available in OS X v10.7 and later.

Declared in NSScrollView.h.

NSScrollViewFindBarPosition

These constants define the position of the find bar in relation to the scroll view.

enum {
   NSScrollViewFindBarPositionAboveHorizontalRuler = 0,
   NSScrollViewFindBarPositionAboveContent = 1,
   NSScrollViewFindBarPositionBelowContent = 2
};
typedef NSInteger NSScrollViewFindBarPosition;
Constants
NSScrollViewFindBarPositionAboveHorizontalRuler

The find bar is displayed above the horizontal ruler, if visible.

Available in OS X v10.7 and later.

Declared in NSScrollView.h.

NSScrollViewFindBarPositionAboveContent

The find bar is displayed above the scroll view content.

Available in OS X v10.7 and later.

Declared in NSScrollView.h.

NSScrollViewFindBarPositionBelowContent

The find bar is displayed below the scroll view content.

Available in OS X v10.7 and later.

Declared in NSScrollView.h.

Notifications

NSScrollViewWillStartLiveMagnifyNotification

Posted at the beginning of a magnify gesture.

The notification object is the scroll view performing the magnification.

This notification indicates that the magnification property is being changed due to user action. This may be due to the user performing a pinch gesture or a smart zoom gesture. When animating the magnification value yourself via the object's animator, this notification is not sent.

Availability
Declared In
NSScrollView.h

NSScrollViewDidEndLiveMagnifyNotification

Posted at the end of a magnify gesture.

The notification object is the scroll view performing the magnification.

This notification indicates that the magnification property is being changed due to user action. This may be due to the user performing a pinch gesture or a smart zoom gesture. When animating the magnification value yourself via the object's animator, this notification is not sent.

Availability
Declared In
NSScrollView.h

NSScrollViewWillStartLiveScrollNotification

Posted on the main thread at the beginning of user-initiated live scroll tracking (gesture scroll or scroller tracking, for example, thumb dragging).

The notification object is the scroll view performing the scroll.

Availability
Declared In
NSScrollView.h

NSScrollViewDidLiveScrollNotification

Posted on the main thread after changing the clipview bounds origin due to a user-initiated event.

Some user-initiated scrolls (for example, scrolling using legacy mice) are not bracketed by a “willStart/didEnd” notification pair.

The notification object is the scroll view performing the scroll.

Availability
Declared In
NSScrollView.h

NSScrollViewDidEndLiveScrollNotification

Posted on the main thread at the end of live scroll tracking.

The notification object is the scroll view performing the scroll.

Availability
Declared In
NSScrollView.h