NSSliderCell 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
NSSliderCell.h
Related sample code

Overview

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 set... methods. If these methods 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.

Tasks

Managing Cell Behavior

Managing the Slider Type

Displaying the Cell

Managing Cell Appearance

Managing Value Limits

Managing Tick Marks

Class Methods

prefersTrackingUntilMouseUp

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

+ (BOOL)prefersTrackingUntilMouseUp
Return Value

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

Discussion

If this method returns YES, 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.
Declared In
NSSliderCell.h

Instance Methods

allowsTickMarkValuesOnly

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

- (BOOL)allowsTickMarkValuesOnly
Return Value

YES if the slider's values are limited to those values represented by tick marks; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSliderCell.h

altIncrementValue

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

- (double)altIncrementValue
Return Value

The amount by which the slider changes its value when the user drags the knob with the Option key held down. Unless you call setAltIncrementValue:, altIncrementValue returns –1.0, and the slider behaves no differently with the Option key down than with it up.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSliderCell.h

barRectFlipped:

Returns the rectangle in which the bar is drawn.

- (NSRect)barRectFlipped:(BOOL)flipped
Parameters
flipped

YES if the coordinate system of the associated NSSlider or NSMatrix is flipped; otherwise NO. 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.
Declared In
NSSliderCell.h

closestTickMarkValueToValue:

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

- (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.
Declared In
NSSliderCell.h

drawBarInside:flipped:

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

- (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.
Declared In
NSSliderCell.h

drawKnob

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

- (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.
Declared In
NSSliderCell.h

drawKnob:

Draws the slider knob in the given rectangle.

- (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.
Declared In
NSSliderCell.h

drawTickMarks

Draws the slider’s tick marks.

- (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.
Declared In
NSSliderCell.h

indexOfTickMarkAtPoint:

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

- (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.
Declared In
NSSliderCell.h

isVertical

Returns an integer indicating the orientation (vertical or horizontal) of the slider.

- (NSInteger)isVertical
Return Value

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.
Declared In
NSSliderCell.h

knobRectFlipped:

Returns the rectangle in which the slider knob is drawn.

- (NSRect)knobRectFlipped:(BOOL)flipped
Parameters
flipped

YES if the coordinate system of the associated NSSlider or NSMatrix is flipped; otherwise NO. 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.
Declared In
NSSliderCell.h

knobThickness

Returns the knob’s thickness.

- (CGFloat)knobThickness
Return Value

The thickness of the slider knob, in pixels. 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.
Declared In
NSSliderCell.h

maxValue

Returns the maximum value the slider can send to its target.

- (double)maxValue
Return Value

The maximum value of the slider. 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSliderCell.h

minValue

Returns the minimum value the slider can send to its target.

- (double)minValue
Return Value

The minimum value of the slider. 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.
Declared In
NSSliderCell.h

numberOfTickMarks

Returns the number of tick marks associated with the slider.

- (NSInteger)numberOfTickMarks
Return Value

The number of tick marks. The tick marks assigned to the minimum and maximum values are included.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSliderCell.h

rectOfTickMarkAtIndex:

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

- (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.
Declared In
NSSliderCell.h

setAllowsTickMarkValuesOnly:

Sets whether the receiver’s values are fixed to the values represented by the tick marks.

- (void)setAllowsTickMarkValuesOnly:(BOOL)flag
Parameters
flag

YES if the slider's values are fixed to the values represented by the slider's tick marks; otherwise NO. For example, if you specify YES 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. This method has no effect if the slider has no tick marks.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSliderCell.h

setAltIncrementValue:

Sets the amount by which the receiver modifies its value when the knob is Option-dragged.

- (void)setAltIncrementValue:(double)increment
Parameters
increment

The amount by which the receiver changes its value when the knob is Option-dragged. This 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, increment should be between 0 and 5.

Discussion

If you don’t call this method, the slider behaves the same regardless of whether the Option key is held down (this is also the result when you call setAltIncrementValue: with an increment of –1).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSliderCell.h

setMaxValue:

Sets the maximum value the slider can send to its target.

- (void)setMaxValue:(double)aDouble
Parameters
aDouble

The slider's maximum value. A horizontal slider sends its maximum value when its knob is all the way to the right; a vertical slider sends its maximum value when its 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.
See Also
Declared In
NSSliderCell.h

setMinValue:

Sets the minimum value the slider can send to its target.

- (void)setMinValue:(double)aDouble
Parameters
aDouble

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSliderCell.h

setNumberOfTickMarks:

Sets the number of tick marks displayed by the receiver.

- (void)setNumberOfTickMarks:(NSInteger)numberOfTickMarks
Parameters
numberOfTickMarks

The number of tick marks displayed by the slider, including those assigned to the minimum and maximum values. 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.
Declared In
NSSliderCell.h

setSliderType:

Sets the type of slider to linear or circular.

- (void)setSliderType:(NSSliderType)sliderType
Parameters
sliderType

A constant indicating the type of the slider. Possible values are described in NSSliderType.

Discussion

If sliderType 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 setNumberOfTickMarks: method to display tick marks, and you can use the setAllowsTickMarkValuesOnly: method 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.
Declared In
NSSliderCell.h

setTickMarkPosition:

Sets where tick marks appear relative to the receiver.

- (void)setTickMarkPosition:(NSTickMarkPosition)position
Parameters
position

A constant indicating the position of the tick marks. Possible values are described in NSTickMarkPosition.

Discussion

This method has no effect if no tick marks have been assigned (that is, if numberOfTickMarks returns 0).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSliderCell.h

sliderType

Returns the slider type, either linear or circular.

- (NSSliderType)sliderType
Return Value

A constant indicating the type of the slider. Possible return values are described in NSSliderType.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSSliderCell.h

tickMarkPosition

Returns the position of the tick marks relative to the receiver.

- (NSTickMarkPosition)tickMarkPosition
Return Value

A constant indicating the position of the tick marks. Possible values are described in NSTickMarkPosition. The default alignments are NSTickMarkBelow and NSTickMarkLeft.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSliderCell.h

tickMarkValueAtIndex:

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

- (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.
Declared In
NSSliderCell.h

trackRect

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

- (NSRect)trackRect
Return Value

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSliderCell.h

Constants

NSTickMarkPosition

Specifies where the tick marks of an NSSliderCell object appear.

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

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

Available in OS X v10.0 and later.

Declared in NSSliderCell.h.

NSTickMarkAbove

Tick marks above (for horizontal sliders).

Available in OS X v10.0 and later.

Declared in NSSliderCell.h.

NSTickMarkLeft

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

Available in OS X v10.0 and later.

Declared in NSSliderCell.h.

NSTickMarkRight

Tick marks to the right (for vertical sliders).

Available in OS X v10.0 and later.

Declared in NSSliderCell.h.

Discussion

These constants are used in setTickMarkPosition: and tickMarkPosition.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSliderCell.h

NSSliderType

The types of sliders, used by setSliderType: and sliderType.

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

A bar-shaped slider.

Available in OS X v10.3 and later.

Declared in NSSliderCell.h.

NSCircularSlider

A circular slider; that is, a dial.

Available in OS X v10.3 and later.

Declared in NSSliderCell.h.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSSliderCell.h