---

NSSlider Class Reference

Overview

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.

Tasks

Asking About the Slider’s Appearance

• – altIncrementValue
• – image
• – knobThickness
• – isVertical

Changing the Slider’s Appearance

• – setAltIncrementValue:
• – setImage:
• – setKnobThickness:

Asking About the Slider’s Title

• – title
• – titleCell
• – titleColor
• – titleFont

Changing the Slider’s Title

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

Asking About the Value Limits

• – maxValue
• – minValue

Changing the Value Limits

• – setMaxValue:
• – setMinValue:

Handling Mouse-down Events

• – acceptsFirstMouse:

Managing Tick Marks

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

Instance Methods

acceptsFirstMouse:

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.

- (BOOL)acceptsFirstMouse:(NSEvent *)mouseDownEvent

Parameters

mouseDownEvent

The mouse-down event.

Return Value

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

Discussion

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

Availability

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

Declared In

NSSlider.h

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 fixes its values to the values represented by its tick marks; otherwise, NO.

Discussion

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

Availability

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

See Also

• – setAllowsTickMarkValuesOnly:

Declared In

NSSlider.h

altIncrementValue

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

- (double)altIncrementValue

Return Value

The amount by which the value changes when the user drags the slider knob with the Option key held down. Unless you call setAltIncrementValue:, altIncrementValue returns –1.0, and the receiver 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

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

See Also

• – indexOfTickMarkAtPoint:

Declared In

NSSlider.h

image

This method has been deprecated. Returns nil.

- (NSImage *)image

Availability

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

See Also

• – setImage:

Declared In

NSSlider.h

indexOfTickMarkAtPoint:

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

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

See Also

• – closestTickMarkValueToValue:

Declared In

NSSlider.h

isVertical

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

- (NSInteger)isVertical

Return Value

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

Declared In

NSSlider.h

knobThickness

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

Availability

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

See Also

• – setKnobThickness:

Declared In

NSSlider.h

maxValue

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

- (double)maxValue

Return Value

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

See Also

• – setMaxValue:

Declared In

NSSlider.h

minValue

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

- (double)minValue

Return Value

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

See Also

• – setMinValue:

Declared In

NSSlider.h

numberOfTickMarks

Returns the number of tick marks associated with the receiver.

- (NSInteger)numberOfTickMarks

Return Value

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 method, the receiving NNSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

Availability

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

See Also

• – setNumberOfTickMarks:

Declared In

NSSlider.h

rectOfTickMarkAtIndex:

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

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

See Also

• – indexOfTickMarkAtPoint:

Declared In

NSSlider.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 should be fixed to the values represented by its tick marks; otherwise NO. 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.

Discussion

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

See Also

• – allowsTickMarkValuesOnly

Declared In

NSSlider.h

setAltIncrementValue:

Sets the amount by which the NSSliderCell modifies its value when the user Option-drags the knob.

- (void)setAltIncrementValue:(double)increment

Parameters

increment

The amount by which the slider's value changes when the user Option–drags its knob. This value 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, increment should be between 0 and 5. If increment is outside that range, the value is unchanged.

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

NSSlider.h

setImage:

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

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

See Also

• – setImage:

Declared In

NSSlider.h

setKnobThickness:

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

- (void)setKnobThickness:(CGFloat)thickness

Parameters

thickness

The thickness of the knob. 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 Mac OS X v10.0 and later.

See Also

• – knobThickness

Declared In

NSSlider.h

setMaxValue:

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

- (void)setMaxValue:(double)maxValue

Parameters

maxValue

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

Availability

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

See Also

• – maxValue

Declared In

NSSlider.h

setMinValue:

Sets the minimum value the receiver can send to its target

- (void)setMinValue:(double)minValue

Parameters

minValue

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

Availability

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

See Also

• – minValue

Declared In

NSSlider.h

setNumberOfTickMarks:

Sets the number of tick marks displayed by the receiver.

- (void)setNumberOfTickMarks:(NSInteger)numberOfTickMarks

Parameters

numberOfTickMarks

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.

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

See Also

• – numberOfTickMarks

Declared In

NSSlider.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. For horizontal sliders, this can be NSTickMarkBelow (the default) or NSTickMarkAbove; for vertical sliders, this can be NSTickMarkLeft (the default) or NSTickMarkRight.

Discussion

This method has no effect if no tick marks have been assigned (that is, numberOfTickMarks returns 0). 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 Mac OS X v10.0 and later.

See Also

• – tickMarkPosition

Declared In

NSSlider.h

setTitle:

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

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

See Also

• – title

Declared In

NSSlider.h

setTitleCell:

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

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

See Also

• – titleCell

Declared In

NSSlider.h

setTitleColor:

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

- (void)setTitleColor:(NSColor *)color

Parameters

color

The title color.

Availability

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

See Also

• – titleColor

Declared In

NSSlider.h

setTitleFont:

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

- (void)setTitleFont:(NSFont *)font

Parameters

font

The title font.

Availability

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

See Also

• – titleFont

Declared In

NSSlider.h

tickMarkPosition

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

- (NSTickMarkPosition)tickMarkPosition

Return Value

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.

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

See Also

• – setTickMarkPosition:

Declared In

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

Declared In

NSSlider.h

title

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

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

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

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

NSSlider.h

---