Inherits from: NSControl : NSView : NSResponder : NSObject
Conforms to: NSCoding
(NSResponder)
NSObject (NSObject)
Declared in: AppKit/NSScroller.h
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. |
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 Alternate-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.
Interface Builder automatically associates NSScrollers with an NSScrollView, allowing you to configure most aspects of scrolling behavior without programming. If you create one programmatically using the constructor the new NSScroller automatically collapses the shorter of its two dimensions to the standard scroller width, as returned by the scrollerWidth class method. In this manner a tall, narrow frame results in a vertical NSScroller and a short, wide frame results in a horizontal NSScroller.
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.
NSScroller is a public class primarily for programmers who decide not to use an NSScrollView but who want to present a consistent user interface. Its use outside of NSScrollViews is discouraged except in cases where the porting of an existing application is made more straightforward. Setting up an NSScroller with a custom container view class (or a completely different kind of target) involves establishing the standard target and action as defined by NSControl, and implementing the target's action method appropriately.
As an NSScroller tracks the mouse, it sends an action message to its target with itself as the argument. The target then performs the scrolling operation based on these things:
As indicated above, the direction and scale of a scrolling operation is determined by the value returned from a hitPart message, which indicates the various parts of an NSScroller in terms of their intended result (not in terms of their location or appearance):
Value | How to Scroll |
Knob |
Directly to the NSScroller's value, as given by floatValue |
KnobSlot |
Directly to the NSScroller's value, as given by floatValue |
DecrementLine |
Up or left by a small amount |
DecrementPage |
Up or left by a large amount |
IncrementLine |
Down or right by a small amount |
IncrementPage |
Down or right by a large amount |
NoPart |
Don't scroll at all |
These part codes are interpreted differently depending on the method you use them with. See the individual method descriptions for hitPart, rectForPart, and testPart for details.
The four decrement/increment values require the target to calculate an appropriate amount to scroll by. Line and page amounts are up to the target or the container view to define. NSScrollView, for example, allows you to set these in Interface Builder or with its setLineScroll: and setPageScroll: methods. Once the target has scrolled the document view by a decrement or increment, it should update the NSScroller's position using setFloatValue:.
The container view or target should also keep tabs on its size and on the size and position of its document view. Any time these change it should update its NSScrollers using setFloatValueAndKnobProportion. NSClipView, for example, overrides most of NSView's setBounds... and setFrame... methods to perform this updating.
These constants specify the different parts of the scroller
Constant | Description |
Knob |
The scroll knob |
KnobSlot |
The slot that the knob moves in |
DecrementLine |
The up or left scroll button |
DecrementPage |
The region of the slot above or to the left of the knob |
IncrementLine |
The down or right scroll button |
IncrementPage |
The region of the slot below or to the right of the knob |
NoPart |
Anywhere outside the scroller |
These consants describe the two scroller buttons:
Constant | Description |
IncrementArrow |
The down or right scroll button |
DecrementArrow |
The up or left scroll button |
These constants specify where the scroller's buttons appear.
Note that on Microsoft Windows scroll buttons appear at either end
of the scroller rather than both on one end. So a value other than ArrowsNone
is
thus reinterpreted on that platform to display the buttons at either
end.
Constant | Description |
ArrowsMaxEnd |
Buttons at bottom or right |
ArrowsMinEnd |
Buttons at top or left |
ArrowsNone |
No buttons |
These constants specify which parts of the scroller are visible:
Constant | Description |
NoParts |
Scroller has neither a knob nor scroll buttons, only the knob slot. |
OnlyArrows |
Scroller has only scroll buttons, no knob. |
AllParts |
Scroller has at least a knob, possibly also scroll buttons. |
- Determining NSScroller size
- scrollerWidth
- 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
public static float scrollerWidth()
public int arrowsPosition()
public void checkSpaceForParts()
public void drawArrow(int arrow, boolean flag)
IncrementArrow
(the
down or right scroll button) or DecrementArrow
(up
or left). 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
public void drawKnob()
See Also: drawArrow, rectForPart
public void drawParts()
public void highlight(boolean flag)
true
,
the appropriate part is drawn highlighted, otherwise it's drawn
normally.See Also: drawArrow, rectForPart
public int hitPart()
Value | How to Scroll |
Knob |
Directly to the NSScroller's value, as given by floatValue |
KnobSlot |
Directly to the NSScroller's value, as given by floatValue |
DecrementLine |
Up or left by a small amount |
DecrementPage |
Up or left by a large amount |
IncrementLine |
Down or right by a small amount |
IncrementPage |
Down or right by a large amount |
NoPart |
Don't scroll at all |
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.
- (id)initWithFrame:(NSRect)frameRect
public float knobProportion()
public NSRect rectForPart(int aPart)
Value | Part |
Knob |
The knob itself |
KnobSlot |
The slot that the knob moves in |
DecrementLine |
The up or left scroll button |
DecrementPage |
The region of the slot above or to the left of the knob |
IncrementLine |
The down or right scroll button |
IncrementPage |
The region of the slot below or to the right of the knob |
Note the interpretations of DecrementPage
and IncrementPage
.
The actual part of an NSScroller that causes page-by-page scrolling
varies from platform to platform, so as a convenience these part
codes refer to useful parts different from the scroll buttons.
Returns ZeroRect
if
the part requested isn't present on the receiver.
See Also: hitPart, testPart, usableParts
public void setArrowsPosition(int location)
Value | Meaning |
ArrowsMaxEnd |
Buttons at bottom or right |
ArrowsMinEnd |
Buttons at top or left |
ArrowsNone |
No buttons |
On Microsoft Windows scroll buttons appear at either
end of the scroller rather than both on one end. A value other than ArrowsNone
is
thus reinterpreted on that platform to display the buttons at either
end.
See Also: arrowsPosition
public void setFloatValueAndKnobProportion(float aFloat, float knobProp)
See Also: - floatValue (NSControl), knobProportion
public int testPart(NSPoint aPoint)
Return Value | Part Identified |
Knob |
The knob itself |
KnobSlot |
The slot that the knob moves in (returned only if there's no knob) |
DecrementLine |
The up or left scroll button |
DecrementPage |
The region of the slot above or to the left of the knob |
IncrementLine |
The down or right scroll button |
IncrementPage |
The region of the slot below or to the right of the knob |
NoPart |
aPoint isn't in the NSScroller |
Note the interpretations of DecrementPage
and IncrementPage
.
The actual part of an NSScroller that causes page-by-page scrolling
varies from platform to platform, so as a convenience these part
codes refer to useful parts different from the scroll buttons.
See Also: hitPart, rectForPart
public void trackKnob(NSEvent theEvent)
public void trackScrollButtons(NSEvent theEvent)
public int usableParts()
Value | Meaning |
NoParts |
Scroller has neither a knob nor scroll buttons, only the knob slot. |
OnlyArrows |
Scroller has only scroll buttons, no knob. |
AllParts |
Scroller has at least a knob, possibly also scroll buttons. |
See Also: checkSpaceForParts, arrowsPosition