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 |
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
-
+ scrollerWidthForControlSize:scrollerStyle: -
+ scrollerWidth -
+ scrollerWidthForControlSize: -
– setControlSize: -
– controlSize
Laying out a Scroller
Setting the Knob Position
-
– setKnobProportion: -
– knobProportion -
– setFloatValue:knobProportion:Deprecated in OS X v10.5
Calculating Layout
Drawing Scroller Parts
-
– drawArrow:highlight: -
– drawKnobSlotInRect:highlight: -
– drawKnob -
– highlight: -
– drawPartsDeprecated in OS X v10.7
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.
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
drawKnobanddrawKnobSlotInRect:highlight:, and not by overridingdrawRect:.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
drawKnobanddrawKnobSlotInRect:highlight:.It likewise performs any event-handling customization by overriding the parts-based methods
testPart:andtrackKnob:, and not by overridingmouseDown:.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.hpreferredScrollerStyle
Returns the style of scrollers that applications should use wherever possible.
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.
See Also
Declared In
NSScroller.hscrollerWidth
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.)
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.hscrollerWidthForControlSize:
Returns the width of the scroller based on controlSize and assuming a scroller style of NSScrollerStyleLegacy. (Deprecated. Use scrollerWidthForControlSize:scrollerStyle: instead.)
Discussion
Valid values for controlSize are described in NSControlSize (NSCell).
Availability
- Available in OS X v10.0 and later.
Declared In
NSScroller.hscrollerWidthForControlSize:scrollerStyle:
Returns the width for scrollers of the receiving class for a given control size and scroller style.
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.hInstance Methods
arrowsPosition
Returns the location of the scroll buttons within the receiver, as described in NSScrollArrowPosition.
Special Considerations
This method has no effect in OS X v10.7 and later.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSScroller.hcheckSpaceForParts
Checks to see if there is enough room in the receiver to display the knob and buttons.
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.hcontrolSize
Returns the size of the receiver.
Discussion
Valid values for controlSize are described in NSControlSize (NSCell).
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSScroller.hcontrolTint
Returns the receiver’s control tint.
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.
See Also
Declared In
NSScroller.hdrawArrow:highlight:
Draws the scroll button indicated by arrow, which is either NSScrollerIncrementArrow (the down or right scroll button) or NSScrollerDecrementArrow (up or left).
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.
See Also
Declared In
NSScroller.hdrawKnob
Draws the knob.
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.
See Also
Declared In
NSScroller.hdrawKnobSlotInRect:highlight:
Draws the portion of the scroller’s track, possibly including the line increment and decrement arrow buttons, that falls in the given rectangle.
Parameters
- slotRect
The rectangle in which to draw the knob slot.
- flag
If
flagisYES, 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.hhighlight:
Highlights or unhighlights the scroll button the user clicked.
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.
See Also
Declared In
NSScroller.hhitPart
Returns a part code indicating the manner in which the scrolling should be performed.
Discussion
See NSScrollerPart for a list of part codes.
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.
Availability
- Available in OS X v10.0 and later.
Declared In
NSScroller.hknobProportion
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).
Availability
- Available in OS X v10.0 and later.
Declared In
NSScroller.hknobStyle
Returns the knob style used by the receiver.
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.
See Also
Declared In
NSScroller.hrectForPart:
Returns the rectangle occupied by aPart, which for this method is interpreted literally rather than as an indicator of scrolling direction.
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.
See Also
Declared In
NSScroller.hscrollerStyle
Returns scroller style used by the receiver.
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.hsetArrowsPosition:
Sets the location of the scroll buttons within the receiver to location, or inhibits their display.
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.
See Also
Declared In
NSScroller.hsetControlSize:
Sets the size of the receiver.
Discussion
Valid values for controlSize are described in NSControlSize (NSCell).
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSScroller.hsetControlTint:
Sets the receiver’s control tint.
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.
See Also
Declared In
NSScroller.hsetKnobProportion:
Sets the proportion of the knob slot the knob should fill.
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.hsetKnobStyle:
Sets the knob style used by the receiver
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.
See Also
Declared In
NSScroller.hsetScrollerStyle:
Sets the scroller style used by the receiver.
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.
See Also
Declared In
NSScroller.htestPart:
Returns the part that would be hit by a mouse-down event at aPoint (expressed in the window’s coordinate system).
Discussion
See NSScrollerPart for a list of possible return values.
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.
See Also
Declared In
NSScroller.htrackKnob:
Tracks the knob and sends action messages to the receiver’s target.
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.htrackScrollButtons:
Tracks the scroll buttons and sends action messages to the receiver’s target.
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.husableParts
Returns a value indicating which parts of the receiver are displayed and usable.
Discussion
See NSUsableScrollerParts for a list of possible values.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSScroller.hConstants
NSScrollerStyle
Constants to specify the scroller style.
enum {
NSScrollerStyleLegacy = 0,
NSScrollerStyleOverlay = 1
};
typedef NSInteger NSScrollerStyle;
Constants
NSScrollerStyleLegacySpecifies legacy-style scrollers as prior to OS X v10.7.
Available in OS X v10.7 and later.
Declared in
NSScroller.h.NSScrollerStyleOverlaySpecifies 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
NSScrollerKnobStyleDefaultSpecifies 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.NSScrollerKnobStyleDarkSpecifies a dark knob.
This style is particularly good against a light background.
Available in OS X v10.7 and later.
Declared in
NSScroller.h.NSScrollerKnobStyleLightSpecifies 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
NSScrollerKnobDirectly to the scroller’s value, as given by
floatValue.Available in OS X v10.0 and later.
Declared in
NSScroller.h.NSScrollerKnobSlotDirectly to the scroller’s value, as given by
floatValue.Available in OS X v10.0 and later.
Declared in
NSScroller.h.NSScrollerDecrementLineUp or left by a small amount.
Available in OS X v10.0 and later.
Declared in
NSScroller.h.NSScrollerDecrementPageUp or left by a large amount.
Available in OS X v10.0 and later.
Declared in
NSScroller.h.NSScrollerIncrementLineDown or right by a small amount.
Available in OS X v10.0 and later.
Declared in
NSScroller.h.NSScrollerIncrementPageDown or right by a large amount.
Available in OS X v10.0 and later.
Declared in
NSScroller.h.NSScrollerNoPartDon’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
NSScrollerIncrementArrowThe down or right scroll button.
Available in OS X v10.0 and later.
Declared in
NSScroller.h.NSScrollerDecrementArrowThe 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
NSScrollerArrowsMaxEndButtons at bottom or right. This constant has been deprecated.
Available in OS X v10.0 and later.
Declared in
NSScroller.h.NSScrollerArrowsMinEndButtons at top or left. This has been deprecated.
Available in OS X v10.0 and later.
Declared in
NSScroller.h.NSScrollerArrowsDefaultSettingButtons are displayed according to the system-wide appearance preferences.
Available in OS X v10.1 and later.
Declared in
NSScroller.h.NSScrollerArrowsNoneNo buttons.
Available in OS X v10.0 and later.
Declared in
NSScroller.h.
NSUsableScrollerParts
These constants specify which parts of the scroller are visible.
enum {
NSNoScrollerParts = 0,
NSOnlyScrollerArrows = 1,
NSAllScrollerParts = 2
};
typedef NSUInteger NSUsableScrollerParts;
Constants
NSNoScrollerPartsSpecifies 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.NSOnlyScrollerArrowsSpecifies that the scroller has only scroll buttons, no knob.
Available in OS X v10.0 and later.
Declared in
NSScroller.h.NSAllScrollerPartsSpecifies 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
For a full discussion, see preferredScrollerStyle.
Availability
- Available in OS X v10.7 and later.
Declared In
NSScroller.h© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-05-01)