Mac Developer Library

Developer

AppKit Framework Reference NSSliderCell Class Reference

Options
Deployment Target:

On This Page
Language:

NSSliderCell

An NSSliderCell object controls the appearance and behavior of an NSSlider object, or of a single slider in an NSMatrix object.

You can customize an NSSliderCell to a certain degree, using its properties. If this don’t give you sufficient flexibility, you can create a subclass. In that subclass, you can override any of the following methods: knobRectFlipped:, drawBarInside:flipped:, drawKnob:, and prefersTrackingUntilMouseUp.

  • The amount by which the slider changes its value when the user Option-drags the knob.

    Declaration

    Swift

    var altIncrementValue: Double

    Objective-C

    @property double altIncrementValue

    Discussion

    By default, the value of this property is -1.0, and the slider behaves no differently with the Option key down than with it up. If you set this property, the number should correspond to the range of values the slider can represent—for example, if the slider has a minimum value of 5 and a maximum value of 10, the value should be between 0 and 5.

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value indicating whether the NSSliderCell continues to track the pointer until the next mouse up.

    Declaration

    Swift

    class func prefersTrackingUntilMouseUp() -> Bool

    Objective-C

    + (BOOL)prefersTrackingUntilMouseUp

    Return Value

    YEStrue if the NSSliderCell continues to track the pointer even after it leaves the cell's tracking rectangle; otherwise, NOfalse. By default, this method returns YEStrue.

    Discussion

    If this method returns YEStrue, users retain control of the knob until they release the mouse button, even if they drag the pointer to the other side of the screen.

    You should not call this method explicitly. Override it if you create a subclass of NSSliderCell that should track the mouse differently.

    Availability

    Available in OS X v10.0 and later.

  • The rectangle within which the cell tracks the pointer while the mouse button is down.

    Declaration

    Swift

    var trackRect: NSRect { get }

    Objective-C

    @property(readonly) NSRect trackRect

    Discussion

    The tracking rectangle includes the slider bar, but not the bezel.

    Availability

    Available in OS X v10.0 and later.

  • The slider type, either linear or circular.

    Declaration

    Swift

    var sliderType: NSSliderType

    Objective-C

    @property NSSliderType sliderType

    Discussion

    The value of this property is a constant indicating the type of the slider. Possible values are described in NSSliderType.

    When the value of this property is NSCircularSlider, then you get a fixed-size circular slider. The minimum value (minValue) is at the top, and the value increases clockwise around the dial. The maximum selectable value is just below maxValue; for example, if maxValue is 360, you can set the dial up to 359.999.

    You can use the numberOfTickMarks property to display tick marks, and you can use the allowsTickMarkValuesOnly property to specify that values are limited to those values represented by tick marks. You can set this control to regular or small sizes; the mini size is not supported.

    Availability

    Available in OS X v10.3 and later.

  • Returns the rectangle in which the bar is drawn.

    Declaration

    Swift

    func barRectFlipped(_ flipped: Bool) -> NSRect

    Objective-C

    - (NSRect)barRectFlipped:(BOOL)flipped

    Parameters

    flipped

    YEStrue if the coordinate system of the associated NSSlider or NSMatrix is flipped; otherwise NOfalse. You can determine whether this is the case by sending the NSView message isFlipped message to the NSMatrix or NSSlider.

    Return Value

    The rectangle in which the bar is drawn, specified in the coordinate system of the NSSlider or NSMatrix with which the receiver is associated. The bar doesn’t include the slider’s bezel or knob.

    Discussion

    You can override this method if custom bar artwork requires specific dimensions.

    Availability

    Available in OS X v10.9 and later.

  • Draws the slider’s tick marks.

    Declaration

    Swift

    func drawTickMarks()

    Objective-C

    - (void)drawTickMarks

    Discussion

    You should not call this method explicitly. It’s included so you can override it in a subclass and draw custom tick marks.

    Availability

    Available in OS X v10.9 and later.

  • Returns the rectangle in which the slider knob is drawn.

    Declaration

    Swift

    func knobRectFlipped(_ flipped: Bool) -> NSRect

    Objective-C

    - (NSRect)knobRectFlipped:(BOOL)flipped

    Parameters

    flipped

    YEStrue if the coordinate system of the associated NSSlider or NSMatrix is flipped; otherwise NOfalse. You can determine whether this is the case by sending the NSView message isFlipped message to the NSMatrix or NSSlider.

    Return Value

    The rectangle in which the knob is drawn, specified in the coordinate system of the NSSlider or NSMatrix with which the receiver is associated.

    The knob rectangle depends on where in the slider the knob belongs—that is, it depends on the receiver’s minimum and maximum values and on the value the position of the knob will represent.

    Availability

    Available in OS X v10.0 and later.

  • Draws the slider’s bar—but not its bezel or knob—inside the specified rectangle.

    Declaration

    Swift

    func drawBarInside(_ aRect: NSRect, flipped flipped: Bool)

    Objective-C

    - (void)drawBarInside:(NSRect)aRect flipped:(BOOL)flipped

    Parameters

    aRect

    The bounds of the slider's bar, not of its interior rectangle.

    flipped

    A Boolean value that indicates whether the cell’s control view—that is, the NSSlider or NSMatrix associated with the NSSliderCell—has a flipped coordinate system.

    Discussion

    You should not call this method explicitly. It’s included so you can override it in a subclass.

    Availability

    Available in OS X v10.0 and later.

    See Also

    – drawKnob:

  • Calculates the rectangle in which the knob should be drawn, then calls drawKnob: to actually draw the knob.

    Declaration

    Swift

    func drawKnob()

    Objective-C

    - (void)drawKnob

    Discussion

    Before this message is sent, a lockFocus method must be sent to the cell’s control view.

    You might call this method if you override one of the display methods belonging to NSControl or NSCell.

    Special Considerations

    If you create a subclass of NSSliderCell, don’t override this method. Override drawKnob: instead.

    Availability

    Available in OS X v10.0 and later.

  • Draws the slider knob in the given rectangle.

    Declaration

    Swift

    func drawKnob(_ knobRect: NSRect)

    Objective-C

    - (void)drawKnob:(NSRect)knobRect

    Parameters

    knobRect

    The rectangle in which to draw the slider knob.

    Discussion

    Before this message is sent, a lockFocus message must be sent to the cell’s control view.

    You should not call this method explicitly. It’s included so you can override it in a subclass.

    Availability

    Available in OS X v10.0 and later.

  • The thickness of the slider knob, in pixels.

    Declaration

    Swift

    var knobThickness: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat knobThickness

    Discussion

    The thickness is defined to be the extent of the knob along the long dimension of the bar. In a vertical slider, a knob’s thickness is its height; in a horizontal slider, its thickness is its width.

    Availability

    Available in OS X v10.0 and later.

  • An integer indicating the orientation (vertical or horizontal) of the slider.

    Declaration

    Swift

    var vertical: Int { get }

    Objective-C

    @property(getter=isVertical, readonly) NSInteger vertical

    Discussion

    The value of this property is 1 if the slider is vertical, 0 if it’s horizontal, and –1 if the orientation can’t be determined (for example, if the slider hasn’t been displayed yet). A slider is defined as vertical if its height is greater than its width.

    Availability

    Available in OS X v10.0 and later.

  • - title (OS X v10.9)

    Returns the slider’s title.

    Deprecation Statement

    A slider doesn’t include a title.

    Declaration

    Objective-C

    - (NSString *)title

    Return Value

    The title. The default title is the empty string (@"").

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    See Also

    – setTitle:

  • - setTitle: (OS X v10.9)

    Sets the title in the bar behind the slider’s knob.

    Deprecation Statement

    A slider doesn’t include a title.

    Declaration

    Objective-C

    - (void)setTitle:(NSString *)title

    Parameters

    title

    The title.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    See Also

    – title

  • - titleCell (OS X v10.9)

    Returns nil.

    Deprecation Statement

    A slider doesn’t include a title.

    Declaration

    Objective-C

    - (id)titleCell

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • - setTitleCell: (OS X v10.9)

    Sets the cell used to draw the slider’s title.

    Deprecation Statement

    A slider doesn’t include a title.

    Declaration

    Objective-C

    - (void)setTitleCell:(NSCell *)aCell

    Discussion

    You only need to call this method if the default title cell, NSTextFieldCell, doesn’t suit your needs—that is, if you want to display the title in a manner that NSTextFieldCell doesn’t permit. When you do choose to override the default, aCell should be an instance of a subclass of NSTextFieldCell.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    See Also

    – titleCell

  • - titleFont (OS X v10.9)

    Returns nil.

    Deprecation Statement

    A slider doesn’t include a title.

    Declaration

    Objective-C

    - (NSFont *)titleFont

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • - titleColor (OS X v10.9)

    Returns nil.

    Deprecation Statement

    A slider doesn’t include a title.

    Declaration

    Objective-C

    - (NSColor *)titleColor

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • - setTitleFont: (OS X v10.9)

    Sets the font used to draw the slider’s title.

    Deprecation Statement

    A slider doesn’t include a title.

    Declaration

    Objective-C

    - (void)setTitleFont:(NSFont *)fontObj

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    See Also

    – titleFont

  • - setTitleColor: (OS X v10.9)

    Sets the color used to draw the slider’s title.

    Deprecation Statement

    A slider doesn’t include a title.

    Declaration

    Objective-C

    - (void)setTitleColor:(NSColor *)newColor

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    See Also

    – titleColor

  • The maximum value the slider can send to its target.

    Declaration

    Swift

    var maxValue: Double

    Objective-C

    @property double maxValue

    Discussion

    A horizontal slider sends its maximum value when the knob is at the right end of the slider; a vertical slider sends it when the knob is at the top. The maximum selectable value for a circular slider is just below maxValue; for example, if maxValue is 360, you can set the dial up to 359.999.

    Availability

    Available in OS X v10.0 and later.

  • The minimum value the slider can send to its target.

    Declaration

    Swift

    var minValue: Double

    Objective-C

    @property double minValue

    Discussion

    A vertical slider sends this value when its knob is at the bottom; a horizontal slider sends it when its knob is all the way to the left; a circular slider sends it when its knob is at the top.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value indicating whether the receiver fixes its values to those values represented by its tick marks.

    Declaration

    Swift

    var allowsTickMarkValuesOnly: Bool

    Objective-C

    @property BOOL allowsTickMarkValuesOnly

    Discussion

    The value of this property is YEStrue if the slider's values are limited to those values represented by tick marks; otherwise, NOfalse. For example, if you specify YEStrue for a slider that has a minimum value of 0, a maximum value of 100, and five markers, the allowable values are 0, 25, 50, 75, and 100. When users move the slider’s knob, it jumps to the tick mark nearest the pointer when the mouse button is released. Setting this property has no effect if the slider has no tick marks.

    Availability

    Available in OS X v10.0 and later.

  • Returns the value of the tick mark closest to the specified value.

    Declaration

    Swift

    func closestTickMarkValueToValue(_ value: Double) -> Double

    Objective-C

    - (double)closestTickMarkValueToValue:(double)aValue

    Parameters

    aValue

    The value for which to obtain the closest tick mark.

    Return Value

    The value of the closest tick mark.

    Availability

    Available in OS X v10.0 and later.

  • Returns the index of the tick mark closest to the location of the slider represented by the specified point.

    Declaration

    Swift

    func indexOfTickMarkAtPoint(_ point: NSPoint) -> Int

    Objective-C

    - (NSInteger)indexOfTickMarkAtPoint:(NSPoint)point

    Parameters

    point

    The point representing the slider location.

    Return Value

    The index of the tick mark closest to the specified location.

    Discussion

    If point is not within the bounding rectangle (plus an extra pixel of space) of any tick mark, the method returns NSNotFound. This method calls rectOfTickMarkAtIndex: for each tick mark on the slider until it finds a tick mark containing point.

    Availability

    Available in OS X v10.0 and later.

  • The number of tick marks associated with the slider, including the tick marks assigned to the minimum and maximum values.

    Declaration

    Swift

    var numberOfTickMarks: Int

    Objective-C

    @property NSInteger numberOfTickMarks

    Discussion

    By default, this value is 0, and no tick marks appear. The number of tick marks assigned to a slider, along with the slider’s minimum and maximum values, determines the values associated with the tick marks.

    Availability

    Available in OS X v10.0 and later.

  • Returns the bounding rectangle of the tick mark at the specified index.

    Declaration

    Swift

    func rectOfTickMarkAtIndex(_ index: Int) -> NSRect

    Objective-C

    - (NSRect)rectOfTickMarkAtIndex:(NSInteger)index

    Parameters

    index

    The index of the tick mark for which to return the bounding rectangle. The minimum-value tick mark is at index 0.

    Return Value

    The bounding rectangle of the specified tick mark.

    Discussion

    If no tick mark is associated with index, the method raises NSRangeException.

    Availability

    Available in OS X v10.0 and later.

  • The position of the tick marks relative to the receiver.

    Declaration

    Swift

    var tickMarkPosition: NSTickMarkPosition

    Objective-C

    @property NSTickMarkPosition tickMarkPosition

    Discussion

    The value of this property is a constant indicating the position of the tick marks. Possible values are described in NSTickMarkPosition. The default alignments are NSTickMarkBelow and NSTickMarkLeft. Setting this property has no effect if no tick marks have been assigned (that is, if numberOfTickMarks is 0).

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s value represented by the tick mark at the specified index.

    Declaration

    Swift

    func tickMarkValueAtIndex(_ index: Int) -> Double

    Objective-C

    - (double)tickMarkValueAtIndex:(NSInteger)index

    Parameters

    index

    The index of the tick mark for which to retrieve the value. The minimum-value tick mark has an index of 0.

    Return Value

    The value represented by the specified tick mark.

    Availability

    Available in OS X v10.0 and later.

Data Types

  • Specifies where the tick marks of an NSSliderCell object appear.

    Declaration

    Swift

    enum NSTickMarkPosition : UInt { case Below case Above static var Left: NSTickMarkPosition { get } static var Right: NSTickMarkPosition { get } }

    Objective-C

    typedef enum _NSTickMarkPosition { NSTickMarkBelow = 0, NSTickMarkAbove = 1, NSTickMarkLeft = NSTickMarkAbove, NSTickMarkRight = NSTickMarkBelow } NSTickMarkPosition;

    Constants

    • Below

      NSTickMarkBelow

      Tick marks below (for horizontal sliders); the default for horizontal sliders.

      Available in OS X v10.0 and later.

    • Above

      NSTickMarkAbove

      Tick marks above (for horizontal sliders).

      Available in OS X v10.0 and later.

    • Left

      NSTickMarkLeft

      Tick marks to the left (for vertical sliders); the default for vertical sliders

      Available in OS X v10.0 and later.

    • Right

      NSTickMarkRight

      Tick marks to the right (for vertical sliders).

      Available in OS X v10.0 and later.

    Discussion

    These constants are used in tickMarkPosition.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The types of sliders, used by sliderType.

    Declaration

    Swift

    enum NSSliderType : UInt { case LinearSlider case CircularSlider }

    Objective-C

    typedef enum { NSLinearSlider = 0, NSCircularSlider = 1 } NSSliderType;

    Constants

    • LinearSlider

      NSLinearSlider

      A bar-shaped slider.

      Available in OS X v10.3 and later.

    • CircularSlider

      NSCircularSlider

      A circular slider; that is, a dial.

      Available in OS X v10.3 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.