---

NSSliderCell Class Reference

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 do not allow 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

Asking About the Cell’s Behavior

• – altIncrementValue
• + prefersTrackingUntilMouseUp
• – trackRect

Setting the Slider Type

• – setSliderType:
• – sliderType

Changing the Cell’s Behavior

• – setAltIncrementValue:

Displaying the Cell

• – knobRectFlipped:
• – drawBarInside:flipped:
• – drawKnob
• – drawKnob:

Asking About the Cell’s Appearance

• – knobThickness
• – isVertical
• – title
• – titleCell
• – titleFont
• – titleColor

Changing the Cell’s Appearance

• – setKnobThickness:
• – setTitle:
• – setTitleCell:
• – setTitleColor:
• – setTitleFont:

Asking About the Value Limits

• – maxValue
• – minValue

Changing the Value Limits

• – setMaxValue:
• – setMinValue:

Managing Tick Marks

• – allowsTickMarkValuesOnly
• – closestTickMarkValueToValue:
• – indexOfTickMarkAtPoint:
• – numberOfTickMarks
• – rectOfTickMarkAtIndex:
• – setAllowsTickMarkValuesOnly:
• – setNumberOfTickMarks:
• – setTickMarkPosition:
• – tickMarkPosition
• – tickMarkValueAtIndex:

Class Methods

prefersTrackingUntilMouseUp

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

+ (BOOL)prefersTrackingUntilMouseUp

Return Value

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

Discussion

If this method returns YES, this means that, once you take hold of a slider’s knob (by putting the cursor inside the cell’s frame rectangle and pressing the mouse button), you retain control of the knob until you release the mouse button, even if you drag the cursor clear to the other side of the screen.

Never call this method explicitly. Override it if you create a subclass of NSSliderCell that you want to track the mouse differently.

Availability

• Available in Mac 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 Mac OS X v10.0 and later.

See Also

• – setAllowsTickMarkValuesOnly:

Declared In

NSSliderCell.h

altIncrementValue

Returns the amount by which the slider changes its value when the user drags with the Option key held down.

- (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 Mac OS X v10.0 and later.

See Also

• – setAltIncrementValue:

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 Mac OS X v10.0 and later.

See Also

• – indexOfTickMarkAtPoint:

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 never invoke this method explicitly. It’s included so you can override it in a subclass.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – drawKnob:

Declared In

NSSliderCell.h

drawKnob

Calculates the rectangle in which the knob should be drawn, then invokes 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 invoke this method if you override one of the display methods belonging to NSControl or NSCell.

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

Availability

• Available in Mac 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 never invoke this method explicitly. It’s included so you can override it in a subclass.

Availability

• Available in Mac OS X v10.0 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 invokes rectOfTickMarkAtIndex: for each tick mark on the slider until it finds a tick mark containing point.

Availability

• Available in Mac 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 Mac 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.

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSSliderCell.h

knobThickness

Returns the slider knob’s thickness, in pixels.

- (CGFloat)knobThickness

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setKnobThickness:

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. 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 Mac OS X v10.0 and later.

See Also

• – setMaxValue:

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 Mac 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 Mac OS X v10.0 and later.

See Also

• – setNumberOfTickMarks:

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 Mac OS X v10.0 and later.

See Also

• – indexOfTickMarkAtPoint:

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 cursor when the mouse button is released. This method has no effect if the slider has no tick marks.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – allowsTickMarkValuesOnly

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 t 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 with the Option key down as with it up. This is also the result when you call setAltIncrementValue: with an increment of –1.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – maxValue
• – minValue

Declared In

NSSliderCell.h

setKnobThickness:

This method has been deprecated. Lets you set the knob’s thickness, measured in pixels.

- (void)setKnobThickness:(CGFloat)thickness

Parameters

thickness

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – knobThickness

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 Mac OS X v10.0 and later.

See Also

• – maxValue

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 Mac OS X v10.0 and later.

See Also

• – minValue

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 Mac OS X v10.0 and later.

See Also

• – numberOfTickMarks

Related Sample Code

• QTKitMovieShuffler

Declared In

NSSliderCell.h

setSliderType:

Sets the type of slider to a bar or a dial.

- (void)setSliderType:(NSSliderType)sliderType

Parameters

sliderType

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

Discussion

If sliderType is NSCircularSlider, then you get a fixed-size round slider. The minimum value (minValue) is at the top, and the value increases as you go 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 Mac OS X v10.3 and later.

See Also

• – sliderType
• – setNumberOfTickMarks:
• – setAllowsTickMarkValuesOnly:

Related Sample Code

• QTKitMovieShuffler

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, numberOfTickMarks returns 0).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – tickMarkPosition

Declared In

NSSliderCell.h

setTitle:

This method has been deprecated. Sets the title in the bar behind the slider’s knob.

- (void)setTitle:(NSString *)title

Parameters

title

The title.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – title

Declared In

NSSliderCell.h

setTitleCell:

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

- (void)setTitleCell:(NSCell *)aCell

Discussion

You only need to invoke 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 Mac OS X v10.0 and later.

See Also

• – titleCell

Declared In

NSSliderCell.h

setTitleColor:

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

- (void)setTitleColor:(NSColor *)color

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – titleColor

Declared In

NSSliderCell.h

setTitleFont:

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

- (void)setTitleFont:(NSFont *)font

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – titleFont

Declared In

NSSliderCell.h

sliderType

Returns the slider type; either a bar or a dial.

- (NSSliderType)sliderType

Return Value

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

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setSliderType:

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 Mac OS X v10.0 and later.

See Also

• – setTickMarkPosition:

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 Mac OS X v10.0 and later.

Declared In

NSSliderCell.h

title

This method has been deprecated. Returns the slider’s title.

- (NSString *)title

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTitle:

Declared In

NSSliderCell.h

titleCell

This method has been deprecated. Returns nil.

- (id)titleCell

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTitleCell:

Declared In

NSSliderCell.h

titleColor

This method has been deprecated. Returns nil.

- (NSColor *)titleColor

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTitleColor:

Declared In

NSSliderCell.h

titleFont

This method has been deprecated. Returns nil.

- (NSFont *)titleFont

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTitleFont:

Declared In

NSSliderCell.h

trackRect

Returns the rectangle within which the cell tracks the cursor 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 Mac OS X v10.0 and later.

Declared In

NSSliderCell.h

Constants

NSTickMarkPosition

Specify 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 Mac OS X v10.0 and later.

Declared in NSSliderCell.h.

NSTickMarkAbove

Tick marks above (for horizontal sliders).

Available in Mac 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 Mac OS X v10.0 and later.

Declared in NSSliderCell.h.

NSTickMarkRight

Tick marks to the right (for vertical sliders).

Available in Mac OS X v10.0 and later.

Declared in NSSliderCell.h.

Discussion

These constants are used in setTickMarkPosition: and tickMarkPosition.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSSliderCell.h

NSSliderType

Define the types of sliders, used by setSliderType: and sliderType.

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

Constants

NSLinearSlider

A bar-shaped slider.

Available in Mac OS X v10.3 and later.

Declared in NSSliderCell.h.

NSCircularSlider

A circular slider; that is, a dial.

Available in Mac OS X v10.3 and later.

Declared in NSSliderCell.h.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSSliderCell.h

---