Mac Developer Library

Developer

AppKit Framework Reference NSSlider Class Reference

Options
Deployment Target:

On This Page
Language:

NSSlider

An NSSlider object displays a range of values for something in the application. Sliders can be vertical or horizontal bars or circular dials. An indicator, or knob, notes the current setting. The user can move the knob in the slider’s bar—or rotate the knob in a circular slider—to change the setting.

The NSSlider class uses the NSSliderCell class to implement its user interface.

  • The type of the slider, such as vertical or circular.

    Declaration

    Swift

    var sliderType: NSSliderType

    Objective-C

    @property NSSliderType sliderType

    Discussion

    See NSSliderType for possible values.

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Swift

    var altIncrementValue: Double

    Objective-C

    @property double altIncrementValue

    Discussion

    By default, the value of this property is –1.0, and the receiver behaves no differently with the Option key down than with it up. The value of this property must fit 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.

  • The knob’s thickness, in pixels. (read-only)

    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, a knob’s thickness is its width.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var vertical: Int { get }

    Objective-C

    @property(getter=isVertical, readonly) NSInteger vertical

    Discussion

    The value of this propert is 1 if the receiver 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.

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

    Declaration

    Swift

    var maxValue: Double

    Objective-C

    @property double maxValue

    Discussion

    The slider's maximum value. A horizontal slider sends its maximum value when the knob is at the right end of the bar; a vertical slider sends it when the knob is at the top.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var minValue: Double

    Objective-C

    @property double minValue

    Discussion

    The slider's minimum value. A vertical slider sends its minimum value when its knob is at the bottom; a horizontal slider, when its knob is all the way to the left.

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value indicating whether the slider accepts a single mouse-down event that simultaneously activates the window and takes hold of the slider’s knob.

    Declaration

    Swift

    func acceptsFirstMouse(_ theEvent: NSEvent?) -> Bool

    Objective-C

    - (BOOL)acceptsFirstMouse:(NSEvent *)mouseDownEvent

    Parameters

    mouseDownEvent

    The mouse-down event.

    Return Value

    YEStrue if the receiver accepts the first mouse-down event; otherwise, NOfalse. Returns YEStrue by default.

    Discussion

    If you want the receiver to wait for its own mouse-down event, you must override this method.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates 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

    YEStrue if the slider fixes its values to the values represented by its tick marks; otherwise, NOfalse. For example, if a slider 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 cursor when the mouse button is released. This method has no effect if the slider has no tick marks. In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

    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 return the closest tick mark.

    Return Value

    The value of the tick mark closest to aValue.

    Discussion

    In its implementation of this method, the receiver simply invokes the method of the same name of its NSSliderCell instance.

    Availability

    Available in OS X v10.0 and later.

  • Returns the index of the tick mark closest to the location of the receiver represented by the given point.

    Declaration

    Swift

    func indexOfTickMarkAtPoint(_ point: NSPoint) -> Int

    Objective-C

    - (NSInteger)indexOfTickMarkAtPoint:(NSPoint)point

    Parameters

    point

    The point representing the location for which to retrieve the tick mark.

    Return Value

    The index of the tick mark closest to the location specified by point. If point is not within the bounding rectangle (plus an extra pixel of space) of any tick mark, the method returns NSNotFound.

    Discussion

    In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance. This method invokes rectOfTickMarkAtIndex: for each tick mark on the slider until it finds a tick mark containing the point.

    Availability

    Available in OS X v10.0 and later.

  • The number of tick marks associated with the receiver.

    Declaration

    Swift

    var numberOfTickMarks: Int

    Objective-C

    @property NSInteger numberOfTickMarks

    Discussion

    The number of the slider's tick marks.The tick marks assigned to the minimum and maximum values are included. In its implementation of this property, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance. The number of tick marks (including those assigned to the minimum and maximum values) displayed by the slider. 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 given 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 retrieve the bounds. 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. In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

    Availability

    Available in OS X v10.0 and later.

  • Determines how the receiver’s tick marks are aligned with it.

    Declaration

    Swift

    var tickMarkPosition: NSTickMarkPosition

    Objective-C

    @property NSTickMarkPosition tickMarkPosition

    Discussion

    A constant indicating the position of the tick marks. Possible values are NSTickMarkBelow, NSTickMarkAbove, NSTickMarkLeft, and NSTickMarkRight (the last two are for vertical sliders). The default alignments are NSTickMarkBelow and NSTickMarkLeft. This property has no effect if no tick marks have been assigned (that is, numberOfTickMarks returns 0). In its implementation of this property, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance

    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 return the value. The minimum-value tick mark has an index of 0.

    Return Value

    The value of the specified tick mark.

    Discussion

    In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

    Availability

    Available in OS X v10.0 and later.

  • - setImage: (OS X v10.9)

    This method has been deprecated. Sets the image the receiver displays in the bar behind its knob.

    Declaration

    Objective-C

    - (void)setImage:(NSImage *)barImage

    Parameters

    barImage

    The image to set.

    Discussion

    The slider may scale and distort barImage to fit inside the bar.

    The knob may cover part of the image. If you want the image to be visible all the time, you’re better off placing it near the slider.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • - image (OS X v10.9)

    This method has been deprecated. Returns nil.

    Declaration

    Objective-C

    - (NSImage *)image

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    See Also

    – setImage:

  • - title (OS X v10.9)

    Returns the receiver’s 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.

  • - titleCell (OS X v10.9)

    This method has been deprecated. Returns nil.

    Declaration

    Objective-C

    - (id)titleCell

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • - titleColor (OS X v10.9)

    This method has been deprecated. Returns nil.

    Declaration

    Objective-C

    - (NSColor *)titleColor

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • - titleFont (OS X v10.9)

    This method has been deprecated. Returns nil.

    Declaration

    Objective-C

    - (NSFont *)titleFont

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • - setTitle: (OS X v10.9)

    This method has been deprecated. Sets the title the receiver displays in the bar behind its knob.

    Declaration

    Objective-C

    - (void)setTitle:(NSString *)barTitle

    Parameters

    barTitle

    The slider's title. The knob may cover part or all of the title. If you want the title to be visible all the time, you’re better off placing a label near the slider.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    See Also

    – title

  • - setTitleCell: (OS X v10.9)

    This method has been deprecated. Sets the cell used to draw the receiver’s title.

    Declaration

    Objective-C

    - (void)setTitleCell:(NSCell *)titleCell

    Parameters

    titleCell

    The cell used to draw the title.

    Discussion

    You only need to invoke this method if the default title cell, NSTextFieldCell, doesn’t suit your needs—that is, you want to display the title in a manner that NSTextFieldCell doesn’t permit. When you do choose to override the default, titleCell 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

  • - setTitleColor: (OS X v10.9)

    This method has been deprecated. Sets the color used to draw the receiver’s title.

    Declaration

    Objective-C

    - (void)setTitleColor:(NSColor *)color

    Parameters

    color

    The title color.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    See Also

    – titleColor

  • - setTitleFont: (OS X v10.9)

    This method has been deprecated. Sets the font used to draw the receiver’s title.

    Declaration

    Objective-C

    - (void)setTitleFont:(NSFont *)font

    Parameters

    font

    The title font.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    See Also

    – titleFont