---

NSScroller

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.

setFloatValueAndKnobProportion

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

Overview

An NSScroller 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 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

Constructors

• NSScroller

Determining NSScroller Size

• scrollerWidth
• scrollerWidthForControlSize
• setControlSize
• controlSize

Laying out an NSScroller

• setArrowsPosition
• arrowsPosition

Setting the Knob Position

• setFloatValueAndKnobProportion
• knobProportion

Calculating Layout

• rectForPart
• testPart
• checkSpaceForParts
• usableParts

Drawing the Parts

• drawArrow
• drawKnob
• drawParts
• highlight

Event Handling

• hitPart
• trackKnob
• trackScrollButtons

Setting Control Tint

• controlTint
• setControlTint

Static Methods

scrollerWidth

Returns the width of “normal-sized” instances.

public static float scrollerWidth()

Discussion

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

scrollerWidthForControlSize

Returns the width of the scroller based on controlSize.

public static float scrollerWidthForControlSize(int controlSize)

Discussion

Valid values for controlSize are described in NSCell’s “Constants.”

Instance Methods

arrowsPosition

Returns the location of the scroll buttons within the receiver, as described under “Constants.”

public int arrowsPosition()

See Also

• setArrowsPosition

checkSpaceForParts

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

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

controlSize

Returns the size of the receiver.

public int controlSize()

Discussion

Valid return values are described in “Constants.”

See Also

• setControlSize

controlTint

Returns the receiver’s control tint.

public int controlTint()

Discussion

Valid return values are described in “Constants.”

See Also

• setControlTint

drawArrow

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

public void drawArrow(int arrow, boolean flag)

Discussion

If flag is true, 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.

See Also

• drawKnob
• rectForPart

drawKnob

Draws the knob

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

See Also

• drawArrow
• rectForPart

drawParts

Caches images for the scroll buttons and knob.

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

highlight

Highlights or unhighlights the scroll button the user clicked.

public void highlight(boolean flag)

Discussion

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

See Also

• drawArrow
• rectForPart

hitPart

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

public int hitPart()

Discussion

See “Constants” 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.

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

public float knobProportion()

rectForPart

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

public NSRect rectForPart(int aPart)

Discussion

See “Constants” for a list of possible values for aPart.

Note the interpretations of DecrementPage and IncrementPage. 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 NSRect.ZeroRect if the part requested isn’t present on the receiver.

See Also

• hitPart
• testPart
• usableParts

setArrowsPosition

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

public void setArrowsPosition(int location)

Discussion

See “Constants” for a list of possible values for location.

See Also

• arrowsPosition

setControlSize

Sets the size of the receiver.

public void setControlSize(int controlSize)

Discussion

Valid values for controlSize are described in “Constants.”

See Also

• controlSize

setControlTint

Sets the receiver’s control tint.

public void setControlTint(int controlTint)

Discussion

Valid values for controlTint are described in “Constants.”

See Also

• controlTint

setFloatValueAndKnobProportion

Sets the position of the knob to aFloat, which is a value from 0.0 (indicating the top or left end) to 1.0 (the bottom or right end).

public void setFloatValueAndKnobProportion(float aFloat, float knobProp)

Discussion

Also sets the proportion of the knob slot filled by the knob to knobProp, also a value from 0.0 (minimal size) to 1.0 (fills the slot).

See Also

• floatValue (NSControl)
• knobProportion

testPart

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

public int testPart(NSPoint aPoint)

Discussion

See “Constants” for a list of possible return values.

Note the interpretations of DecrementPage and IncrementPage. 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.

See Also

• hitPart
• rectForPart

trackKnob

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

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

trackScrollButtons

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

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

usableParts

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

public int usableParts()

Discussion

See “Constants” for a list of possible values.

See Also

• checkSpaceForParts
• arrowsPosition

Constants

These constants specify the different parts of the scroller:

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

These constants specify where the scroller’s buttons appear and are used by arrowsPosition and setArrowsPosition:

These constants specify which parts of the scroller are visible:

These constants specify control tints:

These constants specify control size:

---