NSScroller 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
NSScroller.h
Related sample code

Overview

An NSScroller object controls scrolling of a document view within the clip view of an NSScrollView instance (or potentially of another kind of container view). A scroller displays a slot containing a knob that the user can drag directly to the desired location. The knob indicates both the position within the document view and—by varying in size within the slot—the amount visible relative to the size of the document view.

Prior to OS X v10.7, an NSScroller object can also optionally display scroll buttons. The scroll buttons are a pair of buttons that the user can click to scroll by a small amount (called a line increment or decrement) and Alt-click to scroll by a large amount (called a page increment or decrement).

You normally don’t need to program with scrollers; instead, you typically configure them with an NSScrollView object in a nib file.

Don’t use an scroller when a slider would be more appropriate. An NSSlider object represents a range of values for something in the application and lets the user choose a setting. A scroller represents the relative position of the visible portion of a view and lets the user choose which portion to view.

Tasks

Managing Overlay Style Compatibility

Determining Scroller Size

Laying out a Scroller

Setting the Knob Position

Calculating Layout

Drawing Scroller Parts

Event Handling

Setting Control Tint

Managing Presentation Style

Class Methods

isCompatibleWithOverlayScrollers

Returns a Boolean value that indicates whether the class is compatible with overlay scroller style and behavior.

+ (BOOL)isCompatibleWithOverlayScrollers
Return Value

YES if the the class is compatible with overlay scroller style and behavior, otherwise NO.

Discussion

By default, AppKit assumes that instances of NSScroller subclasses may not be compatible with the way that overlay scrollers are presented, and falls back to the more compatible scroller metrics and behavior of OS X prior to v10.7.

The recommended override technique for a subclass MyCustomScroller that wants to declare itself compatible with overlay scroller presentation is:

+ (BOOL)isCompatibleWithOverlayScrollers {
    return self == [MyCustomScroller class];
}

This implementation ensures compatibility will be properly assessed for both MyCustomScroller and for potentially unknown subclasses thereof.

When it opts in in this manner, an NSScroller subclass specifies that:

  • It performs any appearance customization by overriding the parts-drawing methods drawKnob and drawKnobSlotInRect:highlight:, and not by overriding drawRect:.

    This is necessary to allow for separate knob and track fade in/out. AppKit automatically applies the necessary fade alpha to whatever is drawn by drawKnob and drawKnobSlotInRect:highlight:.

  • It likewise performs any event-handling customization by overriding the parts-based methods testPart: and trackKnob:, and not by overriding mouseDown:.

  • It can deal with the fact that scroller arrows do not exist, and rectForPart: returns empty rects for them.

  • It can accommodate the potentially different size and layout metrics used by overlay scrollers.

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

preferredScrollerStyle

Returns the style of scrollers that applications should use wherever possible.

+ (NSScrollerStyle)preferredScrollerStyle
Return Value

The style of scrollers that applications should use wherever possible.

Discussion

The preferred scroller style is determined by the Appearance preference panel’s “Show scroll bars” setting for the current user, and—when the user's preference is set to “Automatically based on input device”—by the set of built-in and connected pointing devices and the user’s scroll capability preference settings for them. The preferred scroller style may therefore change over time, and applications should be prepared to adapt their user interfaces to the new scroller style if needed.

In most cases, updating to a new scroller style is automatic: When the preferred scroller style changes, AppKit notifies all NSScrollView instances, sending setScrollerStyle: to each with the new style, which causes each scroll view to automatically re-tile (update its layout) to adapt to the new scroller style. Some NSScrollView instances may refuse the new scroller style setting if they cannot accommodate it for compatibility reasons (the presence of accessory views or legacy scroller subclasses prevent use of overlay scrollers), but most instances will switch to the specified new preferred scroller style.

If you need to be notified of changes to the preferred scroller style, you can register to receive NSPreferredScrollerStyleDidChangeNotification notifications.

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

scrollerWidth

Returns the width for scrollers of the receiving class, assuming a control size NSRegularControlSize, and a scroller style of NSScrollerStyleLegacy. (Deprecated. Use scrollerWidthForControlSize:scrollerStyle: instead.)

+ (CGFloat)scrollerWidth
Discussion

NSScrollView uses this value to lay out its components. Subclasses that use a different width should override this method.

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

scrollerWidthForControlSize:

Returns the width of the scroller based on controlSize and assuming a scroller style of NSScrollerStyleLegacy. (Deprecated. Use scrollerWidthForControlSize:scrollerStyle: instead.)

+ (CGFloat)scrollerWidthForControlSize:(NSControlSize)controlSize
Discussion

Valid values for controlSize are described in NSControlSize (NSCell).

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

scrollerWidthForControlSize:scrollerStyle:

Returns the width for scrollers of the receiving class for a given control size and scroller style.

+ (CGFloat)scrollerWidthForControlSize:(NSControlSize)controlSize scrollerStyle:(NSScrollerStyle)scrollerStyle
Parameters
controlSize

A control size.

scrollerStyle

A scroller style.

Return Value

The width for scrollers of the receiving class for controlSize and scrollerStyle.

Discussion

You should use this method in preference to scrollerWidthForControlSize:, which assumes a scroller style of NSScrollerStyleLegacy, and scrollerWidth which in addition assumes a control size of NSRegularControlSize.

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

Instance Methods

arrowsPosition

Returns the location of the scroll buttons within the receiver, as described in NSScrollArrowPosition.

- (NSScrollArrowPosition)arrowsPosition
Special Considerations

This method has no effect in OS X v10.7 and later.

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

checkSpaceForParts

Checks to see if there is enough room in the receiver to display the knob and buttons.

- (void)checkSpaceForParts
Discussion

usableParts returns the state calculated by this method. You should never need to invoke this method; it’s invoked automatically whenever the scroller’s size changes.

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

controlSize

Returns the size of the receiver.

- (NSControlSize)controlSize
Discussion

Valid values for controlSize are described in NSControlSize (NSCell).

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

controlTint

Returns the receiver’s control tint.

- (NSControlTint)controlTint
Discussion

Valid return values are described in NSControlTint.

Special Considerations

This method has no effect in OS X v10.7 and later.

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

drawArrow:highlight:

Draws the scroll button indicated by arrow, which is either NSScrollerIncrementArrow (the down or right scroll button) or NSScrollerDecrementArrow (up or left).

- (void)drawArrow:(NSScrollerArrow)arrow highlight:(BOOL)flag
Discussion

If flag is YES, the button is drawn highlighted; otherwise it’s drawn normally. You should never need to invoke this method directly, but may wish to override it to customize the appearance of scroll buttons.

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

drawKnob

Draws the knob.

- (void)drawKnob
Discussion

You should never need to invoke this method directly, but may wish to override it to customize the appearance of the knob.

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

drawKnobSlotInRect:highlight:

Draws the portion of the scroller’s track, possibly including the line increment and decrement arrow buttons, that falls in the given rectangle.

- (void)drawKnobSlotInRect:(NSRect)slotRect highlight:(BOOL)flag
Parameters
slotRect

The rectangle in which to draw the knob slot.

flag

If flag is YES, any scroll arrow button that falls within slotRect is drawn highlighted; otherwise it's drawn normally.

Discussion

Only one arrow button will be shown highlighted at a time, so you can expect this method to sometimes be invoked with a slotRect that encompasses only one arrow.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSScroller.h

highlight:

Highlights or unhighlights the scroll button the user clicked.

- (void)highlight:(BOOL)flag
Discussion

The receiver invokes this method while tracking the mouse; you should not invoke it directly. If flag is YES, the appropriate part is drawn highlighted; otherwise it’s drawn normally.

Special Considerations

This method has no effect in OS X v10.7 and later.

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

hitPart

Returns a part code indicating the manner in which the scrolling should be performed.

- (NSScrollerPart)hitPart
Discussion

This method is typically invoked by an NSScrollView object to determine how to scroll its document view when it receives an action message from the scroller.

See NSScrollerPart for a list of part codes. In OS X v10.7 and later, this method no longer returns NSScrollerIncrementLine or NSScrollerDecrementLine.

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

knobProportion

Returns the portion of the knob slot the knob should fill, as a floating-point value from 0.0 (minimal size) to 1.0 (fills the slot).

- (CGFloat)knobProportion
Availability
  • Available in OS X v10.0 and later.
Declared In
NSScroller.h

knobStyle

Returns the knob style used by the receiver.

- (NSScrollerKnobStyle)knobStyle
Return Value

The knob style used by the receiver.

Discussion

The value of this property does not affect legacy scrollers. NSScrollerKnobStyleDefault is appropriate for a wide range of content, but in some cases choosing an alternative knob style may enhance visibility of the scroller knob atop some kinds of content.

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

rectForPart:

Returns the rectangle occupied by aPart, which for this method is interpreted literally rather than as an indicator of scrolling direction.

- (NSRect)rectForPart:(NSScrollerPart)aPart
Discussion

See NSScrollerPart for a list of possible values for aPart.

Note the interpretations of NSScrollerDecrementPage and NSScrollerIncrementPage. The actual part of an NSScroller that causes page-by-page scrolling varies, so as a convenience these part codes refer to useful parts different from the scroll buttons.

Returns NSZeroRect if the part requested isn’t present on the receiver.

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

scrollerStyle

Returns scroller style used by the receiver.

- (NSScrollerStyle)scrollerStyle
Return Value

The scroller style used by the receiver.

Discussion

For a scroller that’s managed by an NSScrollView object, the setter is automatically invoked by the scroll view with the appropriate setting, according to the user’s Appearance preference settings and possibly what pointing device(s) are present (see preferredScrollerStyle).

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

setArrowsPosition:

Sets the location of the scroll buttons within the receiver to location, or inhibits their display.

- (void)setArrowsPosition:(NSScrollArrowPosition)location
Discussion

See NSScrollArrowPosition for a list of possible values for location.

Special Considerations

This method has no effect in OS X v10.7 and later.

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

setControlSize:

Sets the size of the receiver.

- (void)setControlSize:(NSControlSize)controlSize
Discussion

Valid values for controlSize are described in NSControlSize (NSCell).

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

setControlTint:

Sets the receiver’s control tint.

- (void)setControlTint:(NSControlTint)controlTint
Discussion

Valid values for controlTint are described in NSControlTint.

Special Considerations

This method has no effect in OS X v10.7 and later.

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

setKnobProportion:

Sets the proportion of the knob slot the knob should fill.

- (void)setKnobProportion:(CGFloat)proportion
Parameters
proportion

A floating point value between 0.0 (minimal size) and 1.0 (fills the entire slot).

Discussion

Code that targets OS X v10.5 and later should use -setKnobProportion: and setDoubleValue:: in preference to the deprecated method that they replace, setFloatValue:knobProportion:. These methods provide more uniform, Key Value Coding-compatible access to the two values, and allow for a double-precision scroll position.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSScroller.h

setKnobStyle:

Sets the knob style used by the receiver

- (void)setKnobStyle:(NSScrollerKnobStyle)newKnobStyle
Parameters
newKnobStyle

The new knob style for the receiver.

Discussion

For a full discussion, see knobStyle.

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

setScrollerStyle:

Sets the scroller style used by the receiver.

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

The new scroller style for the receiver.

Discussion

For a full discussion, see scrollerStyle.

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

testPart:

Returns the part that would be hit by a mouse-down event at aPoint (expressed in the window’s coordinate system).

- (NSScrollerPart)testPart:(NSPoint)aPoint
Discussion

See NSScrollerPart for a list of possible return values. In OS X v10.7 and later, this method no longer returns NSScrollerIncrementLine or NSScrollerDecrementLine.

Note the interpretations of NSScrollerDecrementPage and NSScrollerIncrementPage. The actual part of a scroller that causes page-by-page scrolling varies, so as a convenience these part codes refer to useful parts different from the scroll buttons.

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

trackKnob:

Tracks the knob and sends action messages to the receiver’s target.

- (void)trackKnob:(NSEvent *)theEvent
Discussion

This method is invoked automatically when the receiver receives theEvent mouse-down event in the knob; you should not invoke it directly.

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

trackScrollButtons:

Tracks the scroll buttons and sends action messages to the receiver’s target.

- (void)trackScrollButtons:(NSEvent *)theEvent
Discussion

This method is invoked automatically when the receiver receives theEvent mouse-down event in a scroll button; you should not invoke this method directly.

Special Considerations

This method is not invoked in OS X v10.7 and later.

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

usableParts

Returns a value indicating which parts of the receiver are displayed and usable.

- (NSUsableScrollerParts)usableParts
Discussion

See NSUsableScrollerParts for a list of possible values.

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

Constants

NSScrollerStyle

Constants to specify the scroller style.

enum {
   NSScrollerStyleLegacy       = 0,
   NSScrollerStyleOverlay      = 1
};
typedef NSInteger NSScrollerStyle;
Constants
NSScrollerStyleLegacy

Specifies legacy-style scrollers as prior to OS X v10.7.

Available in OS X v10.7 and later.

Declared in NSScroller.h.

NSScrollerStyleOverlay

Specifies overlay-style scrollers in OS X v10.7 and later.

Available in OS X v10.7 and later.

Declared in NSScroller.h.

NSScrollerKnobStyle

Specify different knob styles.

enum {
   NSScrollerKnobStyleDefault  = 0,
   NSScrollerKnobStyleDark     = 1,
   NSScrollerKnobStyleLight    = 2
};
typedef NSInteger NSScrollerKnobStyle;
Constants
NSScrollerKnobStyleDefault

Specifies a dark knob with a light border.

This is the default style; it is good against any background.

Available in OS X v10.7 and later.

Declared in NSScroller.h.

NSScrollerKnobStyleDark

Specifies a dark knob.

This style is particularly good against a light background.

Available in OS X v10.7 and later.

Declared in NSScroller.h.

NSScrollerKnobStyleLight

Specifies a light knob.

This style is particularly good against a dark background.

Available in OS X v10.7 and later.

Declared in NSScroller.h.

NSScrollerPart

These constants specify the different parts of the scroller:

enum {
   NSScrollerNoPart            = 0,
   NSScrollerDecrementPage     = 1,
   NSScrollerKnob              = 2,
   NSScrollerIncrementPage     = 3,
   NSScrollerDecrementLine     = 4,
   NSScrollerIncrementLine     = 5,
   NSScrollerKnobSlot          = 6
};
typedef NSUInteger NSScrollerPart;
Constants
NSScrollerKnob

Directly to the scroller’s value, as given by floatValue.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerKnobSlot

Directly to the scroller’s value, as given by floatValue.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerDecrementLine

Up or left by a small amount. (Deprecated. This constant is not needed in OS X v10.7 and later.)

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerDecrementPage

Up or left by a large amount.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerIncrementLine

Down or right by a small amount. (Deprecated. This constant is not needed in OS X v10.7 and later.)

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerIncrementPage

Down or right by a large amount.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerNoPart

Don’t scroll at all.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerArrow

These constants describe the two scroller buttons and are used by drawArrow:highlight:. (Deprecated. This enum is not needed in OS X v10.7 and later.)

enum {
   NSScrollerIncrementArrow = 0,
   NSScrollerDecrementArrow = 1
};
typedef NSUInteger NSScrollerArrow;
Constants
NSScrollerIncrementArrow

The down or right scroll button.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerDecrementArrow

The up or left scroll button.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollArrowPosition

These constants specify where the scroller’s buttons appear and are used by arrowsPosition and setArrowsPosition:. (Deprecated. This enum is not needed in OS X v10.7 and later.)

enum {
   NSScrollerArrowsMaxEnd                = 0, /* Previously deprecated. */
   NSScrollerArrowsMinEnd                = 1, /* Previously deprecated. */
   NSScrollerArrowsDefaultSetting        = 0,
   NSScrollerArrowsNone                  = 2
};
typedef NSUInteger NSScrollArrowPosition;
Constants
NSScrollerArrowsMaxEnd

Buttons at bottom or right. This constant has been deprecated.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerArrowsMinEnd

Buttons at top or left. This has been deprecated.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerArrowsDefaultSetting

Buttons are displayed according to the system-wide appearance preferences.

Available in OS X v10.1 and later.

Declared in NSScroller.h.

NSScrollerArrowsNone

No buttons.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSUsableScrollerParts

These constants specify which parts of the scroller are visible. (Deprecated. This enum is not needed in OS X v10.7 and later.)

enum {
   NSNoScrollerParts     = 0,
   NSOnlyScrollerArrows  = 1,
   NSAllScrollerParts    = 2
};
typedef NSUInteger NSUsableScrollerParts;
Constants
NSNoScrollerParts

Specifies that the scroller has neither a knob nor scroll buttons, only the knob slot.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSOnlyScrollerArrows

Specifies that the scroller has only scroll buttons, no knob.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

NSAllScrollerParts

Specifies that the scroller has at least a knob, possibly also scroll buttons.

Available in OS X v10.0 and later.

Declared in NSScroller.h.

Notifications

NSPreferredScrollerStyleDidChangeNotification

Posted if the preferred scroller style changes.

For a full discussion, see preferredScrollerStyle.

Availability
Declared In
NSScroller.h