Mac Developer Library

Developer

AppKit Framework Reference NSScroller Class Reference

Options
Deployment Target:

On This Page
Language:

NSScroller

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

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.

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

    Declaration

    Swift

    class func isCompatibleWithOverlayScrollers() -> Bool

    Objective-C

    + (BOOL)isCompatibleWithOverlayScrollers

    Return Value

    YEStrue if the the class is compatible with overlay scroller style and behavior, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Deprecation Statement

    Use the knobProportion property and the setDoubleValue: method instead.

    Declaration

    Objective-C

    - (void)setFloatValue:(float)aFloat knobProportion:(CGFloat)proportion

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

    See Also

    floatValue (NSControl)
    knobProportion

  • The proportion of the knob slot that the knob should fill.

    Declaration

    Swift

    var knobProportion: CGFloat

    Objective-C

    @property CGFloat knobProportion

    Discussion

    This property contains a floating-point value from 0.0 (minimal size) to 1.0 (fills the slot).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func rectForPart(_ partCode: NSScrollerPart) -> NSRect

    Objective-C

    - (NSRect)rectForPart:(NSScrollerPart)partCode

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func testPart(_ thePoint: NSPoint) -> NSScrollerPart

    Objective-C

    - (NSScrollerPart)testPart:(NSPoint)thePoint

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func checkSpaceForParts()

    Objective-C

    - (void)checkSpaceForParts

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A value that indicates which parts of the receiver are displayed and usable. (read-only)

    Declaration

    Swift

    var usableParts: NSUsableScrollerParts { get }

    Objective-C

    @property(readonly) NSUsableScrollerParts usableParts

    Discussion

    See NSUsableScrollerParts for a list of possible values.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func drawArrow(_ whichArrow: NSScrollerArrow, highlight flag: Bool)

    Objective-C

    - (void)drawArrow:(NSScrollerArrow)whichArrow highlight:(BOOL)flag

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func drawKnobSlotInRect(_ slotRect: NSRect, highlight flag: Bool)

    Objective-C

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

    Parameters

    slotRect

    The rectangle in which to draw the knob slot.

    flag

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Draws the knob.

    Declaration

    Swift

    func drawKnob()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • drawParts - drawParts (OS X v10.7)

    Caches images for the scroll buttons and knob.

    Declaration

    Objective-C

    - (void)drawParts

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Highlights or unhighlights the scroll button the user clicked.

    Declaration

    Swift

    func highlight(_ flag: Bool)

    Objective-C

    - (void)highlight:(BOOL)flag

    Discussion

    The receiver invokes this method while tracking the mouse; you should not invoke it directly. If flag is YEStrue, 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • hitPart hitPart Property

    A part code indicating the manner in which the scrolling should be performed. (read-only)

    Declaration

    Swift

    var hitPart: NSScrollerPart { get }

    Objective-C

    @property(readonly) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func trackKnob(_ theEvent: NSEvent)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func trackScrollButtons(_ theEvent: NSEvent)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The scroller’s control tint.

    Declaration

    Swift

    var controlTint: NSControlTint

    Objective-C

    @property NSControlTint controlTint

    Discussion

    The valid values for controlTint are described in NSControlTint.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func preferredScrollerStyle() -> NSScrollerStyle

    Objective-C

    + (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, setting the scrollerStyle property of 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

    See Also

    scrollerStyle

  • The scroller style for this scroller.

    Declaration

    Swift

    var scrollerStyle: NSScrollerStyle

    Objective-C

    @property NSScrollerStyle scrollerStyle

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

    For a list of valid scroller styles, see NSScrollerStyle.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • knobStyle knobStyle Property

    The scroller’s knob style.

    Declaration

    Swift

    var knobStyle: NSScrollerKnobStyle

    Objective-C

    @property NSScrollerKnobStyle knobStyle

    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.

    For a list of possible values, see NSScrollerKnobStyle.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Constants to specify the scroller style.

    Declaration

    Swift

    enum NSScrollerStyle : Int { case Legacy case Overlay }

    Objective-C

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

    Constants

    • Legacy

      NSScrollerStyleLegacy

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

      Available in OS X v10.7 and later.

    • Overlay

      NSScrollerStyleOverlay

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

      Available in OS X v10.7 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Specify different knob styles.

    Declaration

    Swift

    enum NSScrollerKnobStyle : Int { case Default case Dark case Light }

    Objective-C

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

    Constants

    • Default

      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.

    • Dark

      NSScrollerKnobStyleDark

      Specifies a dark knob.

      This style is particularly good against a light background.

      Available in OS X v10.7 and later.

    • Light

      NSScrollerKnobStyleLight

      Specifies a light knob.

      This style is particularly good against a dark background.

      Available in OS X v10.7 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • These constants specify the different parts of the scroller:

    Declaration

    Swift

    enum NSScrollerPart : UInt { case NoPart case DecrementPage case Knob case IncrementPage case DecrementLine case IncrementLine case KnobSlot }

    Objective-C

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

    Constants

    • Knob

      NSScrollerKnob

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

      Available in OS X v10.0 and later.

    • KnobSlot

      NSScrollerKnobSlot

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

      Available in OS X v10.0 and later.

    • DecrementLine

      NSScrollerDecrementLine

      Up or left by a small amount.

      This constant is not needed in OS X v10.7 and later.

      Available in OS X v10.0 and later.

    • DecrementPage

      NSScrollerDecrementPage

      Up or left by a large amount.

      Available in OS X v10.0 and later.

    • IncrementLine

      NSScrollerIncrementLine

      Down or right by a small amount.

      This constant is not needed in OS X v10.7 and later.

      Available in OS X v10.0 and later.

    • IncrementPage

      NSScrollerIncrementPage

      Down or right by a large amount.

      Available in OS X v10.0 and later.

    • NoPart

      NSScrollerNoPart

      Don’t scroll at all.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    This enum is not needed in OS X v10.7 and later.

    Declaration

    Swift

    enum NSScrollerArrow : UInt { case IncrementArrow case DecrementArrow }

    Objective-C

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

    Constants

    • IncrementArrow

      NSScrollerIncrementArrow

      The down or right scroll button.

      Available in OS X v10.0 and later.

    • DecrementArrow

      NSScrollerDecrementArrow

      The up or left scroll button.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants specify where the scroller’s buttons appear and are used by the arrowsPosition property.

    This enum is not needed in OS X v10.7 and later.

    Declaration

    Swift

    enum NSScrollArrowPosition : UInt { case ScrollerArrowsMaxEnd case ScrollerArrowsMinEnd case ScrollerArrowsNone }

    Objective-C

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

    Constants

    • ScrollerArrowsMaxEnd

      NSScrollerArrowsMaxEnd

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

      Available in OS X v10.0 and later.

    • ScrollerArrowsMinEnd

      NSScrollerArrowsMinEnd

      Buttons at top or left. This has been deprecated.

      Available in OS X v10.0 and later.

    • NSScrollerArrowsDefaultSetting

      NSScrollerArrowsDefaultSetting

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

      Available in OS X v10.1 and later.

    • ScrollerArrowsNone

      NSScrollerArrowsNone

      No buttons.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants specify which parts of the scroller are visible.

    This enum is not needed in OS X v10.7 and later.

    Declaration

    Swift

    enum NSUsableScrollerParts : UInt { case NoScrollerParts case OnlyScrollerArrows case AllScrollerParts }

    Objective-C

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

    Constants

    • NoScrollerParts

      NSNoScrollerParts

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

      Available in OS X v10.0 and later.

    • OnlyScrollerArrows

      NSOnlyScrollerArrows

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

      Available in OS X v10.0 and later.

    • AllScrollerParts

      NSAllScrollerParts

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

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.