---

NSScroller Class Reference

Class at a Glance

An NSScroller object is a user control for scrolling a document view within a container view. You normally don’t need to program with NSScrollers, as Interface Builder allows you to fully configure them with an NSScrollView.

Principal Attributes

• Scrolling by small and large increments

• Proportional knob showing visible amount of document

Commonly Used Methods

hitPart

Indicates where the user clicked the NSScroller.

floatValue (NSControl)

Returns the position of the NSScroller’s knob.

setFloatValue:knobProportion:

Sets the position and size of the NSScroller’s knob.

Overview

An NSScroller object controls scrolling of a document view within an NSScrollView’s clip view (or potentially another kind of container view). It typically displays 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), plus 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. You can configure whether an NSScroller object uses scroll buttons, but it always draws the knob when there’s room for it.

Don’t use an NSScroller when an NSSlider would be better. A slider 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

Determining NSScroller Size

• + scrollerWidth
• + scrollerWidthForControlSize:
• – setControlSize:
• – controlSize

Laying out an NSScroller

• – setArrowsPosition:
• – arrowsPosition

Setting the Knob Position

• – setKnobProportion:
• – knobProportion
• – setFloatValue:knobProportion: Deprecated in Mac OS X v10.5

Calculating Layout

• – rectForPart:
• – testPart:
• – checkSpaceForParts
• – usableParts

Drawing the Parts

• – drawArrow:highlight:
• – drawKnobSlotInRect:highlight:
• – drawKnob
• – drawParts
• – highlight:

Event Handling

• – hitPart
• – trackKnob:
• – trackScrollButtons:

Setting Control Tint

• – controlTint
• – setControlTint:

Class Methods

scrollerWidth

Returns the width of “normal-sized” instances.

+ (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 Mac OS X v10.0 and later.

Declared In

NSScroller.h

scrollerWidthForControlSize:

Returns the width of the scroller based on controlSize.

+ (CGFloat)scrollerWidthForControlSize:(NSControlSize)controlSize

Discussion

Valid values for controlSize are described in NSCell’s NSControlSize.

Availability

• Available in Mac OS X v10.0 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

Availability

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

See Also

• – setArrowsPosition:

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 NSScroller’s size changes.

Availability

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

Declared In

NSScroller.h

controlSize

Returns the size of the receiver.

- (NSControlSize)controlSize

Discussion

Valid return values are described in NSControlSize.

Availability

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

See Also

• – setControlSize:

Declared In

NSScroller.h

controlTint

Returns the receiver’s control tint.

- (NSControlTint)controlTint

Discussion

Valid return values are described in NSControlTint.

Availability

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

See Also

• – setControlTint:

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 Mac OS X v10.0 and later.

See Also

• – drawKnob
• – rectForPart:

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 Mac OS X v10.0 and later.

See Also

• – drawArrow:highlight:
• – rectForPart:

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

- (void)drawKnobSlotInRect:(NSRect)slotRecthighlight:(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 Mac OS X v10.5 and later.

Declared In

NSScroller.h

drawParts

Caches images for the scroll buttons and knob.

- (void)drawParts

Discussion

It’s invoked only once when the NSScroller is created. You may want to override this method if you alter the look of the NSScroller, but you should never invoke it directly.

Availability

• Available in Mac OS X v10.0 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.

Availability

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

See Also

• – drawArrow:highlight:
• – rectForPart:

Declared In

NSScroller.h

hitPart

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

- (NSScrollerPart)hitPart

Discussion

See NSScrollerPart for a list of part codes.

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

Availability

• Available in Mac 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 Mac OS X v10.0 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 Mac OS X v10.0 and later.

See Also

• – hitPart
• – testPart:
• – usableParts

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.

Availability

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

See Also

• – arrowsPosition

Declared In

NSScroller.h

setControlSize:

Sets the size of the receiver.

- (void)setControlSize:(NSControlSize)controlSize

Discussion

Valid values for controlSize are described in NSControlSize.

Availability

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

See Also

• – controlSize

Related Sample Code

• Quartz Composer QCTV
• WhackedTV

Declared In

NSScroller.h

setControlTint:

Sets the receiver’s control tint.

- (void)setControlTint:(NSControlTint)controlTint

Discussion

Valid values for controlTint are described in NSControlTint.

Availability

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

See Also

• – controlTint

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 Mac OS X 10.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 Mac OS X v10.5 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.

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.

Availability

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

See Also

• – hitPart
• – rectForPart:

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

Availability

• Available in Mac 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 Mac OS X v10.0 and later.

See Also

• – checkSpaceForParts
• – arrowsPosition

Declared In

NSScroller.h

Constants

NSScrollerPart

These constants specify the different parts of the scroller:

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

Constants

NSScrollerKnob

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

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerKnobSlot

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

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerDecrementLine

Up or left by a small amount.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerDecrementPage

Up or left by a large amount.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerIncrementLine

Down or right by a small amount.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerIncrementPage

Down or right by a large amount.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerNoPart

Don’t scroll at all.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

Availability

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

Declared In

NSScroller.h

NSScrollerArrow

These constants describe the two scroller buttons and are used by drawArrow:highlight::

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

Constants

NSScrollerIncrementArrow

The down or right scroll button.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerDecrementArrow

The up or left scroll button.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

Availability

• Available in Mac 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:.

typedef enum _NSScrollArrowPosition {
   NSScrollerArrowsMaxEnd            = 0,
   NSScrollerArrowsMinEnd            = 1,
   NSScrollerArrowsDefaultSetting    = 0,
   NSScrollerArrowsNone              = 2
} NSScrollArrowPosition;

Constants

NSScrollerArrowsMaxEnd

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

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerArrowsMinEnd

Buttons at top or left. This has been deprecated.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSScrollerArrowsDefaultSetting

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

Available in Mac OS X v10.1 and later.

Declared in NSScroller.h.

NSScrollerArrowsNone

No buttons.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

Availability

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

Declared In

NSScroller.h

NSUsableScrollerParts

These constants specify which parts of the scroller are visible.

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

Constants

NSNoScrollerParts

Scroller has neither a knob nor scroll buttons, only the knob slot.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSOnlyScrollerArrows

Scroller has only scroll buttons, no knob.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

NSAllScrollerParts

Scroller has at least a knob, possibly also scroll buttons.

Available in Mac OS X v10.0 and later.

Declared in NSScroller.h.

Availability

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

Declared In

NSScroller.h

---